home *** CD-ROM | disk | FTP | other *** search
/ MacFormat 1997 January / macformat-046.iso / Shareware Plus / Developers / EnterAct / EnterAct Stuff / Documentation / EnterAct 3 Manual < prev    next >
Encoding:
Text File  |  1996-10-08  |  353.9 KB  |  9,405 lines  |  [TEXT/KEEN]
  1. ****************ENTERACT™ USER’s MANUAL*****************
  2. -    -    -    -    -    -    -    -    -    -    -    -
  3. Preface and Copyright
  4. -    -    -    -    -    -    -    -    -    -    -    -
  5. ____
  6. Copyright © 1991-1996 by Dynabyte. EnterAct 3.7, by Ken Earle.
  7. All rights reserved.
  8.  
  9. EnterAct's basic text engine is a modified form of Roy Wood's
  10. "TE32K" package. You can find it on the net (search for "Roy Wood"
  11. or "TE32K").
  12.  
  13. "More Files" provides some nifty file handling features.
  14.  
  15. "Jims CDEFs" (or "Jim's CDEFs") does the square buttons and tab panels.
  16.  
  17. Thanks to Zelko Jagaric, Wai Choi, Rob Gibson, Steve Olson,
  18. Jean François Cassan, Mark Wong, Scott Jenson, Bill Sears, Sandra Lakin,
  19. Nicolas Berloquin, Romain Vignes &c for help and constructive abuse.
  20.  
  21.                 (Using EnterAct? <Option>zoom to open this window up)
  22.  
  23. You can reach me at:
  24. Ken Earle
  25. 697 Spadina Ave
  26. Toronto, ON
  27. CANADA
  28. M5S 2J1
  29.  
  30. kearle@interlog.com                        via Internet (preferred)
  31. 73073,2166                                    via CompuServe (I'll be dropping this)
  32. ____
  33.  
  34. The 68K version of EnterAct 3 is FREE. No catch.
  35. There is, as yet, no released native PPC version.
  36.  
  37. "hAWK", "Read Resource", their associated source code and
  38. manuals, and the Drag_on Modules interface are yours to keep,
  39. free, no matter what. They are governed by the Free Software
  40. Foundation's "copyleft", as described in the document "copying
  41. hAWK", included with your EnterAct package.
  42.  
  43. You may distribute full copies of EnterAct (omitting no files from
  44. the compressed archive that comprises EnterAct), provided you
  45. do not charge for EnterAct itself. This includes CD distribution.
  46.  
  47. EnterAct is an editor for creating, maintaining, and reviewing C, C++
  48. and Java code. EnterAct has many capabilities (most notably
  49. real-time automatic definition and prototype display, even out of
  50. first-draft code) that just aren’t "out there" yet. This is a
  51. finite-lived product, intended to fill the gap until EnterAct’s best
  52. features are available elsewhere. Let’s hope it doesn’t take more
  53. than a year or two. That having been said, please note that
  54. EnterAct itself is a solid editor. It’s been around since 1989.
  55.  
  56. If you just want to use EnterAct as a "definition viewer" to help
  57. out some other editor, see the section
  58. ____
  59. §    EnterAct as a "definition finder"
  60. ____
  61. (to get there, use "Enter Selection" and "Find Again" on the above line).
  62.  
  63. Metrowerks codewarriors, please see Appendix 5.
  64.  
  65. Symantec lightspeeders, please see Appendix 4.
  66.  
  67. (Using EnterAct? <Option> click in the title bar here)
  68.  
  69. MPWers, start doing your happy dance.
  70.  
  71. For the very very impatient:
  72.     •1    Start up EnterAct ( if you haven't yet).
  73.     •2    Make a project (New Project), just as with THINK C etc.
  74.     Select your preferred folder for <header> files in the next dialog that
  75.     appears, or Cancel to use the folder that contains EnterAct.
  76.     •3    Drag files or folders onto the project window to add files.
  77.     •4    "Update Dictionary". See "DON’T GIVE UP" a page or so below
  78.     if you run into a problem. Usually problems are rare, fixes are easy.
  79.     •5    Pick the "AutoLook" command (it explains itself).
  80.     •6    Open a project source file and browse around. Double-click on
  81.     or click just after any name that you’d like to see a definition
  82.     or prototype for. Watch the AutoLook window. Press <Enter>.
  83.     •7    Come on back here, and learn about all the other good stuff
  84.     (persistent lookup windows, cross-referencing, Automark, browser,
  85.     hyperlinks, the hAWK language, code templates, persistent undo, etc).
  86.  
  87. For the just very impatient: see "EnterAct in brief" instead of this.
  88. Included there are details on using EnterAct as a "definition viewer"
  89. while working with other editors.
  90.  
  91. -    -    -    -    -    -    -    -    -    -    -    -
  92. Requirements
  93. -    -    -    -    -    -    -    -    -    -    -    -
  94. (§)    Network and team users please read this
  95. EnterAct does not keep files open, except when in the act of
  96. reading and writing them. EnterAct is, however, SourceServer
  97. aware, and won't allow changes to a file that have been checked
  98. out as read-only unless you issue a "Modify Read Only" command
  99. or enable EnterAct's "ignore ckid's" option.
  100. So use (multiple copies of) EnterAct only if you have some way of
  101. ensuring that you won't have several people working on the same
  102. copy of a file at the same time (such as SourceServer/Projector).
  103.  
  104. (§)    System requirements
  105. System 7 required. Mac II speed (!! that is, a 68020 running
  106. at 16 mHz) is recommended if your project contains more than about
  107. 500K of text in source and header files combined. A hard disk is a
  108. practical necessity. A large screen (>= 16 inches) will
  109. allow you to take better advantage of EnterAct’s information
  110. lookup capabilities. EnterAct requires 2 Meg of memory minimum, 
  111. 7-8 Meg for big projects. The price of power.
  112.  
  113. A minimum configuration that provides all-round pleasant performance:
  114. 68040 @ 25Mhz, 12Meg RAM installed, Virtual Memory ON, 7 Meg
  115. partition for EnterAct, 1/2 Gig hard drive, System 7.5.3. And at least an
  116. 832x624 screen, preferably 1024x768.
  117.  
  118. EnterAct is intended for creating, maintaining, and reviewing Symantec,
  119. MPW, and MetroWerks C/C++/Java code. You may in rare cases
  120. find one or two small difficulties right at first (see DON’T GIVE UP
  121. just below) but you should find that EnterAct understands your
  122. C/C++/Java, and even your “C--” (first-draft stuff).
  123.  
  124. Feel free to print this manual (use EnterAct so the pictures will print).
  125. The benefits of having it on disk are that you can use Find on the
  126. table of contents and elsewhere to jump to topics of interest, and
  127. that this document is marked with chapter headings—hold down the
  128. <Command> key and click in the title bar to view the marker menu for
  129. this file. You may also encounter this doc in HTML form.
  130.  
  131. -    -    -    -    -    -    -    -    -    -    -    -
  132. DON’T GIVE UP
  133. -    -    -    -    -    -    -    -    -    -    -    -
  134. DON’T GIVE UP if you attempt to "Update Dictionary" and the parser
  135. complains about your perfectly good source: quite often, this first
  136. problem will be your last, and easy to fix. (Note with v3.0.5
  137. EnterAct is smarter about handling complicated preprocessor
  138. tangles -- if you get stuck, please let me know and I
  139. will try to fix the problem at my end. My tech support address
  140. is up above. As of this writing EnterAct runs into problems
  141. only with rather pathological practices, such as duplicated
  142. comment starts [this check can be turned off in the Options
  143. dialog], aliases for keywords, and one or two other oddities
  144. as described in the "Source code restrictions" chapter.)
  145.  
  146. The commonest problem involves conditional #defines which
  147. duplicate important punctuation (here '{'), such as
  148. ____
  149.     #ifdef GO_LONG
  150.     long GetArrayIndex(void) {
  151.     #else
  152.     short GetArrayIndex(void) {
  153.     #endif
  154. ____
  155. —although this particular example doesn't bother EnterAct. If
  156. you do run into a problem it will almost certainly be something
  157. similar, involving duplicated punctuation such as the two '{'s above.
  158. The fix for this sort of problem is to recast the definition slightly
  159. to remove the duplicated punctuation:
  160. ____
  161.     #ifdef GO_LONG
  162.     long GetArrayIndex(void)
  163.     #else
  164.     short GetArrayIndex(void)
  165.     #endif
  166.     {
  167. ____
  168.  
  169. Similarly, if a construction such as
  170. ____
  171.     struct Thing
  172.     #ifdef _cplus_
  173.     : public BaseThing
  174.     #endif
  175.     {....
  176. ____
  177. causes a problem it will work fine if recast as
  178. ____
  179.     #ifdef _cplus_
  180.     struct Thing : public BaseThing
  181.     #else
  182.     struct Thing
  183.     #endif
  184.     {...
  185. ____
  186. although once again this example is handled correctly
  187. by EnterAct.
  188. (Note in this case the definition that appears first will be the
  189. one that appears in your Browser window.)
  190. Nested comment starts ( /*.../*...*/) will also cause the parser
  191. to hiccup. Best, fix the comment so it has one start and one end.
  192. Second best, pick "Options" from the Edit menu and deselect
  193. "Detect nested comment starts".
  194.  
  195. -    -    -    -    -    -    -    -    -    -    -    -
  196. CONTENTS
  197. -    -    -    -    -    -    -    -    -    -    -    -
  198. (Each line in quotes «» below is a "Go to" link: to go to a chapter,
  199. click on its line and select "Go to" from the Search menu.
  200. For more on "Go to" links, see chapter 17.  These chapter links
  201. are available in the popup marker menu, which you can bring up
  202. by holding down the <Command> key and clicking in the title bar.
  203.  
  204. Section names are also listed here, though they are not links or
  205. markers: to go to a section, select the name including the '§', and
  206. then use "Enter Selection" and "Find Again" from the Search menu.
  207. While within a chapter, you can advance from section to section
  208. by searching for just the '§' character, which is an <Option><6>.)
  209.  
  210. «01   Introduction»
  211. «02   About EnterAct»
  212. §    When to use EnterAct
  213. §    An overview
  214. §    Looking ahead
  215. «03   Getting started»
  216. «04   Definitions and conventions»
  217. (chapter 05 has been deleted)
  218. «06   Whirlwind tour»
  219. «07   Source code restrictions»
  220. §    Why not just compilable code?
  221. §    Aliases
  222. §    Obviously unnecessary parentheses
  223. §    Nested comment starts
  224. §    Preprocessor tangles
  225. §    All–or–nothing macro’s
  226. «08   Projects»
  227. §    Introduction
  228. §    Project files
  229. §    Creating a project
  230. §    Selecting your <system> folder
  231. §    Three panes—.c, .h, plain text
  232. §    Adding Java files
  233. §    Add Files—the one-at-a-time way
  234. §    Adding files from a list
  235. §    Add All In Folder—the fast way
  236. §    Add Mac Headers
  237. §    Add THINK Headers
  238. §    Add Standard C Headers
  239. §    The active pane
  240. §    Remove File
  241. §    Remove •'d Files
  242. §    Custom file extensions
  243. §    Distinguishing ".h" from <.h>
  244. §    Copy and search in the project window
  245. §    Project memory needs
  246. §    Multi-file selection
  247. §    Project context restoration
  248. §    Switching to other projects
  249. §    Tips
  250. «09   Dictionaries»
  251. §    Introduction
  252. §    What’s in a dictionary
  253. §    Building your dictionary
  254. §    Keeping it up to date
  255. §    How long will it take?
  256. §    Show Dictionary
  257. «10   Lookup»
  258. §    AutoLook
  259. §    Regular lookup (press <Enter>)
  260. §    <Enter> for lookup, advancing, scrolling
  261. §    Looking up the clip (press <Command><Enter>)
  262. §    Reverse lookup (press <Shift><Enter>)
  263. §    “Sounds like” lookup (press <Option><Enter>)
  264. §    Viewing other entries in lookup windows
  265. §    For faster lookup
  266. §    Hints with lookup
  267. §    Number of lookup windows
  268. §    Number of entries per lookup
  269. §    Keeping lookups around
  270. §    Looking up your notes
  271. §    EnterAct as a "definition finder" for other editors
  272. §    Looking it up with THINK Reference or Toolbox Assistant
  273. «11   Seeing where a term is defined»
  274. §    <Option>double–click
  275. §    Find Definition
  276. §    If there are multiple definitions
  277. §    Other ways of finding definitions
  278. «12   Browsing»
  279. §    The Browse command
  280. §    Finding classes in the Browser window
  281. §    Method and class popups
  282. §    Browsing classes without the browser
  283. §    Browsing methods without the browser
  284. «13   Documents and windows»
  285. §    New, Open, Close
  286. §    Save, Save As, Revert
  287. §    Close and Save Documents
  288. §    Autorevert
  289. §    Modify Read Only
  290. §    Saving window locations
  291. §    ... without being pestered
  292. §    Newly opened windows can be long or short
  293. §    <Option>–Zoom zooms just the length
  294. §    Number of windows at one time
  295. §    The Windows menu
  296. §    The display box
  297. §    Printing
  298. «14   Editing»
  299. §    Introduction
  300. §    Undo
  301. §    Typing, Cut, Copy, Clear
  302. §    Paste preserves indentation
  303. §    Drag and Drop for text
  304. §    Code templates
  305. §    Selection: front, non–front
  306. §    Paste Selection Behind
  307. §    Font, font size, tabs
  308. §    Shift Left / Right
  309. §    Reformat Selection
  310. §    Syntax coloring
  311. §    Graphic nesting display
  312. §    Arrow keys for moving around
  313. §    Illustrating your text
  314. «15   Balance»
  315. §    Checks everything
  316. §    Shows the error location
  317. §    Balancing a file
  318. §    Balancing a specific delimiter
  319. §    Nested and bad comments
  320. §    Starting in the middle
  321. §    The asm problem
  322. «16   Search»
  323. §    Introduction
  324. §    Find is modeless
  325. §    Find options
  326. §    Batch Find options
  327. §    Dual Batch Find
  328. §    <Tab> and <Return>
  329. §    Find again
  330. §    Enter selection
  331. §    Recent finds are remembered
  332. §    Replace
  333. §    Replace and Find Again
  334. §    Replace All
  335. §    Multi–file searches
  336. §    Skip '-' : excluding files from a search
  337. §    THINK Find commands
  338. «17   “Go” commands»
  339. §    Go to Top/Bottom
  340. §    Go to
  341. §    Going to included files
  342. §    Going to text positions
  343. §    Going to markers
  344. §    Go Back
  345. «18   Markers and the Locations menu»
  346. §    Introduction
  347. §    Mark
  348. §    Marker menus
  349. §    Unmark
  350. §    Automark
  351. §    Copying marker names
  352. §    The Locations menu
  353. «19   Options, under the Edit menu»
  354. §    Introduction
  355. §    Number of lookup windows
  356. §    Number of entries per lookup window
  357. §    Remembering window locations
  358. §    Long or short windows
  359. §    Reformat Selection options
  360. §    Detect nested comment starts
  361. §    Ignore 'ckid's
  362. §    Relocate files automatically
  363. §    Automark source files
  364. §    Save source/headers marks
  365. §    Append arguments for automarked functions
  366. §    Record Find, Find Again, Find Definition
  367. «20   Switching to other applications»
  368. §    Under the Finder (System 6)
  369. §    Under MultiFinder (or System 7 or later)
  370. §    Check the disk for changes
  371. §    Working with THINK C
  372. «21   Show activities»
  373. §    Introduction
  374. §    What’s recorded
  375. §    Recording limitations
  376. §    Showing your recent activities
  377. §    What’s shown
  378. §    Temporary, obsolete, and undone activities
  379. §    Updated file names
  380. §    Reviewing activities
  381. §    Selective single undo
  382. §    Reverting a file
  383. §    Turning activity recording on and off
  384. «22  "Index" commands»
  385. §    Functions…
  386. §    Cross-Reference…
  387. §    #Includes…
  388. §    Marker Names…
  389. §    Potential Locals
  390. §    Standard Metrics
  391. §    Check Prototypes
  392. «23  Some thoughts on using EnterAct»
  393. §    Projects are cheap
  394. §    Learning from or reviewing code
  395. §    On documenting your work
  396. «24  If there's a problem»
  397. §    Out of memory
  398. §    Dictionary problems
  399. §    Lookup problems
  400. §    Editing problems
  401. §    Balance problems
  402. «25  License agreement, tech support»
  403. §    Technical support
  404. §    License
  405. «26  Appendix 1: Drag_on Modules»
  406. «27  Appendix 2: Calling hAWK programs»
  407. §    Calling hAWK from the menu
  408. §    Calling hAWK with a command line
  409. «28  Appendix 4: EnterAct as THINK's editor»
  410. §    Requirements
  411. §    Installing EnterAct as THINK’s editor
  412. §    Starting a session
  413. §    Working with EnterAct as THINK’s editor
  414. §    Using THINK’s Find commands from EnterAct
  415. «29  Appendix 5: EnterAct and Code Warrior»
  416. «30  Appendix 6: the Scripts menu»
  417.  
  418. (for all about the Drag_on Modules, please see
  419. «hAWK User’s Manual» and «Read Resource Manual»
  420. included with this package, as well as Appendices 1 and 2 here)
  421.  
  422. -    -    -    -    -    -    -    -    -    -    -    -
  423. Introduction
  424. -    -    -    -    -    -    -    -    -    -    -    -
  425. Feeling slightly disoriented? That’s just the anesthetic wearing off.
  426. You now have several megabytes of new memory installed in your head,
  427. preloaded with the important facts on everything of interest in your
  428. source code. To access your new memory, click after the name of any
  429. function, struct, define, etc that you’d like to remember in detail,
  430. and glance at the "AutoLook" window.
  431.  
  432. Welcome to EnterAct. If you’re at light speed, prepare for warp drive.
  433. If you’re learning C/C++/Java, you’ll find that the ability to  look up
  434. anything of potential interest gives you more than total recall:
  435. you now have an on–line personal tutor.
  436.  
  437. If you just want to use EnterAct as a "definition viewer" to help
  438. out some other editor, see the section
  439.     §    EnterAct as a "definition finder"
  440. (to get there, use "Enter Selection" and "Find Again" on the above line).
  441.  
  442. This manual is not as impersonal as it perhaps should be, for
  443. which the author apologizes, however insincerely. My name is Ken
  444. Earle, I’m responsible to you for EnterAct’s performance, and since
  445. several of EnterAct’s editing enhancements will be new to you I
  446. will occasionally intrude a personal opinion or bit of advice. For
  447. the most part, though, you should put on your Adventure hat and
  448. expect to take EnterAct in your own direction. If you’ve
  449. done some programming in C/C++ on the Mac, you’ll find that EnterAct
  450. is very easy to get used to. EnterAct is intended to complement
  451. MPW, Symantec, or CodeWarrior (or Sun's Java), which you will
  452. need for compiling and testing your code. For creating,
  453. maintaining, learning from, and documenting code—read on.
  454.  
  455.  
  456. (§)    60 second warmup
  457. EnterAct uses a project window to keep track of your files, as does
  458. THINK C for example. However, the main purpose of an EnterAct project
  459. is to allow you to build a dictionary of all terms in your project,
  460. for rapid lookup. There are three panes in an EnterAct project window,
  461. containing your .c, .h, and documentation files from left to right
  462. respectively. The easiest way to add files to your project is to drag
  463. files/folder onto your project window. To build a dictionary, select
  464. “Update Dictionary”. Unless there are major errors in your source code,
  465. this will zip along at 2-3 files per second. (If you hit a problem, see
  466. DON’T GIVE UP up above, around line 131 for easy fixes to most
  467. problems.) Double–click on any file name in the project window to
  468. view a file. To look up a term, double-click on it, or click just after
  469. it (or of course type it in) and press <Enter>. Select “AutoLook” to put
  470. EnterAct’s automatic definition retriever on-screen, and it will keep up
  471. with you as you edit and click about. You should find that "AutoLook"
  472. by itself can fill most of your information needs.
  473.  
  474.  
  475. (§)    Onwards
  476. What next? If you read straight ahead to the end of the “Whirlwind
  477. tour” you’ll have a good grasp of the basics. Reading the remainder
  478. of the manual at some point is a good idea. You will find that many
  479. things that were relatively complicated or tedious before, such as
  480. information lookup, integrating documentation with code, file and
  481. window management, picking up where you left off, etc, are now much
  482. simpler, some to the point of being completely automatic. Inevitably,
  483. when tasks become simpler, new possibilities and approaches spring to
  484. mind.
  485.  
  486. You can use EnterAct as a replacement for THINK’s editor (THINK
  487. version 6 and later, the “use external editor” Edit option in
  488. THINK)—see Appendix 4 for the easy how-to. EnterAct also sends
  489. "touch" events to any running CodeWarrior compilation
  490. environment. 
  491.  
  492. After you feel comfortable with EnterAct, please take a look at the
  493. “hAWK User’s Manual” on disk. Many useful programs are supplied for
  494. this powerful little language, they’re easy to run, and hAWK does its
  495. work in the background.
  496.  
  497. And remember, take a break every hour!
  498.  
  499. -    -    -    -    -    -    -    -    -    -    -    -
  500. About EnterAct
  501. -    -    -    -    -    -    -    -    -    -    -    -
  502. §    When to use EnterAct
  503. EnterAct is a standalone, project-oriented, language-aware programmer’s
  504. editor designed to smooth the process of creating C, C++, and Java code.
  505. You should find EnterAct useful for the following tasks:
  506.     •    requirements analysis, specification, and design document creation
  507.         or review
  508.     •    creating, maintaining and reviewing source code
  509.     •    as a "definition finder", helping editors that aren't as aware
  510.     •    linking support documents and source code
  511.     •    debugging sessions that require extensive source code review
  512.     •    keeping a log of your activities
  513.     •    oddjobs such as multi-file search and replace, automatic source code
  514.         generation, cross-referencing, algorithm prototyping, deleting or
  515.         copying a list of files, etc etc (via “Index” commands and hAWK,
  516.         both under the EnterAct menu).
  517.  
  518. You'll need a compiler/debugger for compiling and testing your
  519. code, and a resource editor will round out your code creation
  520. environment.
  521.  
  522. EnterAct can be used in place of THINK’s editor (the “use external
  523. editor” Edit option in THINK version 6/7). For the simple setup
  524. required, see Appendix 4.
  525.  
  526. To use EnterAct as a "definition finder" with other editors:
  527.     •    read enough here to learn how to create a project, build
  528.     a dictionary, and show the "AutoLook" window. Knowing
  529.     how to call up "lookup" windows by pressing the <Enter>
  530.     key is also useful. 
  531.     •    when you're using the other editor, also run an EnterAct
  532.     project with contents roughly corresponding to the code
  533.     you're working on - have the "AutoLook" window open,
  534.     as the frontmost text window in EnterAct. Your project
  535.     dictionary should be reasonably up to date.
  536.     •    to look up a term with EnterAct; Copy it in the other editor,
  537.     and switch to EnterAct. If you don't immediately see the
  538.     definition in the AutoLook window (rare), press
  539.     <Command><Enter>. To look up the class or struct that
  540.     contains a particular member, press <Shift><Command><Enter>.
  541.  
  542. §    An overview
  543. EnterAct provides a variety of capabilities in several different areas
  544. to make creating and reviewing code simpler. As the following summary
  545. suggests, you do have a handful of new concepts to become comfortable
  546. with. But for the most part you’ll find just new ways of looking at
  547. old problems, and it shouldn’t be long before you take it all for
  548. granted.
  549.  
  550.  
  551. >    Information management
  552.     •    each EnterAct project stores, for instant retrieval:
  553.         •    the prototype of every method and function (including static and
  554.             in-line)
  555.         •    and the full definition of every class, struct, union, enum, enum
  556.             constant, #define’d constant or macro, typedef, and variable
  557.  
  558.         provided the definition or declaration occurs at the top level of
  559.         your project source code, or within a class. As a special case, #define’s
  560.         within struct, union, and enum bodies are also recorded. (Hereafter,
  561.         “definition” will be used as shorthand for “definition or prototype”).
  562.     •    Definitions can be stored for any C/C++/Java file you
  563.         specify, including toolbox headers, standard library files, class
  564.         source or headers, and of course your own source files, even if they
  565.         are under development (typically EnterAct can tolerate or compensate
  566.         for almost all first-draft errors and omissions)
  567.     •    the “AutoLook” window automatically displays the definition of any
  568.         name that you select or click after, keeping up with you as you edit
  569.         and mouse around. It also serves as a spelling checker
  570.     •    for more permanent displays of definitions, or to look up a term when
  571.     you’ve forgotten its correct spelling, double-clicking on or clicking
  572.     after the name and pressing the <Enter> key creates a separate window
  573.     holding the definition. This is called "regular” lookup, and the
  574.     resulting window shows either all variant definitions, if your spelling
  575.     was exact, or closest matches, based on runs of matching characters,
  576.     if your spelling was off
  577.     •    for phonetic or “sounds like” lookup, press <Option><Enter> instead
  578.     •    for reverse or “struct for member” lookup, press <Shift><Enter> to
  579.     view all structs, classes, and unions whose definitions mention the
  580.     name
  581.     •    results for regular, phonetic, and reverse lookup are shown in a
  582.     new separate “lookup” window, politely sized and placed. Hold down the
  583.     <Option> key and click in its title bar to select from a popup menu
  584.     listing the definitions that were retrieved for the name being looked up
  585.     •    as a result of the above approach, you can show several definitions
  586.     at once from the same file or different files in separate, self-managed
  587.     windows.
  588.     •    EnterAct's "Browse" window does the expected things (and more),
  589.     and works with first-draft C++ or Java code. And it looks pretty.
  590.  
  591. >    File and window management
  592.     •    an EnterAct project window has three panes, showing source, header,
  593.         and documentation file names in separate alphabetical columns. Any
  594.         file can be opened by double-clicking on its name (or hit <return>)
  595.     •    since Enteract is not a compiler, there is no need to set up code
  596.         segments. As a result, EnterAct’s “Add All In Folder” command can
  597.         add all of the files in a folder to your project with a single click
  598.         (including, optionally, all files in subfolders), automatically placing
  599.         source, header, and documentation files in their appropriate panes.
  600.         Dragging files or folders onto a project window works the same way.
  601.     •    all Mac headers, THINK C headers, or standard C headers can be added
  602.         to your project with single separate menu commands
  603.     •    multi-file selections (a generalization of multi-file searching)
  604.         can be made right in the project window
  605.     •    windows can remember their screen location and size—and, if you so
  606.         choose, won’t pester you about saving changes if all you changed was
  607.         the location or size
  608.     •    when EnterAct opens a file for the first time, it bases the width
  609.         of the window on the first 20 lines of the file
  610.     •    <Option>-zoom drops down the bottom of a window, not affecting the
  611.         width.
  612.     •    text files are saved safely. Project saving is automatic, and this
  613.         is threaded into the background when possible.
  614.  
  615. >    Editing
  616.     •    smart paste of code blocks reduces the need to “Shift” left or right
  617.     •    the “Paste Selection Behind” command combines Copy, switch to the
  618.         window just behind, and Paste over what is selected there. It’s
  619.         undoable (in EnterAct even “Replace All” is undoable), and to help you
  620.         anticipate results the selection in your next-to-front window is
  621.         outlined in a box
  622.     •    full Drag & Drop for text
  623.     •    “Balance” handles comments and strings, and can balance a whole file
  624.         at once. If there is an error, you will be shown where it is
  625.     •    now and then, a picture is worth a thousand words. For these
  626.         occasions, you can place and display a picture in any text document,
  627.         even a source file (put it inside a comment, and the compiler will
  628.         never know) -- search here for "Illustrating your text"
  629.  
  630. >    Context restoration
  631.     •    “project context restoration”: when you close an EnterAct project,
  632.         it keeps a list of your project files that were open at the time; and
  633.         when you later reopen the project, your working documents will reopen
  634.         at the same time, placed on the screen where you left them (also called
  635.         the “painless Quit”) 
  636.     •    “activity review”: the “Show Activities” command displays a list
  637.         of the last 10,240 things you have done, in plain English, with full
  638.         contents of all text inserts and deletes. With this display, you can:
  639.         •    review your progress when making complicated changes
  640.         •    accurately bring your “Log” or “Version History” up to date if you
  641.             let this lapse for a bit
  642.         •    selectively undo a single activity
  643.         •    revert files to recover earlier versions
  644.     •    “safe switching”: EnterAct will optionally save your documents when
  645.         you switch out, and refresh them from disk when switching back if
  646.         you changed any with some other application. This restores the
  647.         synchronisation between EnterAct and other applications, and helps
  648.         prevent losing changes to a file.
  649.  
  650. >    Context alteration ("navigation”)
  651.     •    Automatic marking of source files whenever you open or save
  652.         a file, including all function, method, and class definitions.
  653.         (To access a document’s marker menu, hold down the <Option> or
  654.         <Command> key and click in the title bar of its window)
  655.     •    “Go to” accepts a file name followed by line number, or file name
  656.     followed by marker name, or any one of file name, line number, or
  657.     marker name. Useful for:
  658.         •    putting fixed links in your documents with file name followed by
  659.             line number (such as /* See App_Main.c 389 */ )
  660.         •    maintained links, consisting of file name followed by marker name
  661.             (such as /* See «MyApp Design Notes» «2.3 Custom Resources» */
  662.             To generate the text for a link of the form «file name» «marker
  663.             name», hold down the<Shift> and  either <Option> or <Command> keys
  664.             while clicking in the title bar of the window that has the mark; when
  665.             you select the mark from the resulting popup marker menu, the text
  666.             will be copied to your clipboard. Both file and marker name may be
  667.             abbreviated or slightly incorrect, eg
  668.             /* See «Design N» «Custom Rez» */
  669.         •    jumping to locations as reported in the “Show Activities” display
  670.         •    jumping to locations generated by hAWK programs
  671.             ($CompareFiles, $MFS_SuperLister, and many others)
  672.             and also locations generated by several of the "Index" commands,
  673.             such as "Cross-Reference..."
  674.     •    “Go Back” lets you toggle between two locations, in one or two files
  675.     •    jumping to a definition (<Option> double-click) works with toolbox
  676.         headers, first-draft code, and your own notes, almost always going
  677.         straight to the definition with no stumbling over a mention in a
  678.         comment, or a prototype. This allows you to use defined term names in
  679.         source or documentation as true “hyperlinks”.
  680.     •    the Locations menu provides "global" (project-independent) markers.
  681.  
  682. >    The best little language in the world
  683.     •    “hAWK” is a project-oriented version of “AWK”. AWK has long been
  684.         the C programmer’s little language of choice, and hAWK, with its
  685.         simple “three clicks and run” interface, is as easy to invoke as any
  686.         macro language (there's a command line too)
  687.     •    with one click, you can choose to have a program take its input from
  688.         the front text file in EnterAct, or all files selected for multi-file
  689.         operations in your EnterAct project
  690.     •    hAWK is a full programming language, modelled after C but simpler
  691.         in many ways, with many additional built-in capabilities (especially
  692.         for dealing with text)
  693.     •    use supplied hAWK programs to: generate a list of full path names
  694.         for all files in a project, list all occurrences of a word or string
  695.         or regular expression, copy or erase files, translate a C declaration
  696.         into English, list all potential local variables in a C function under
  697.         development, compare files, etc
  698.     •    and you can write your own programs to: check the contents of custom
  699.         resources or file data, prototype algorithms, and in general handle
  700.         any odd job having to do with text files that you can spell out an
  701.         algorithm for (using the fullest implementation of regular expressions
  702.         available anywhere) -- I'm working on "text to html" at the moment....
  703.     •    as of version 3, you can write "magic clipboard" programs in hAWK
  704.         that will monitor EnterAct's clipboard, and, when conditions you
  705.         specify are met, will do anything you like to the clipboard's
  706.         contents. Useful for mowing down repetitive but moderately
  707.         complicated tasks (eg changing old-style C function declarations
  708.         to the new prototype style, changing /**/ comments to //). Once
  709.         your hAWK program is running, all you do is Copy and Paste. Typically
  710.         these programs flash the menu bar to indicate that the clipboard
  711.         has been altered.
  712.     •    "Code templates" make it easy to fire off a hAWK program by using
  713.         a command line -- see «27  Appendix 2: Calling hAWK programs» below.
  714.  
  715. >    Using EnterAct as THINK’s editor
  716.     •    EnterAct works fine by itself, but if you have version 6 or
  717.     later of THINK C and sufficient memory you can use EnterAct as
  718.     a replacement for THINK’s own editor (this is the “use external
  719.     editor” option described in your THINK manual).
  720.     •    using EnterAct as THINK’s editor eliminates the need to
  721.     “Make” your THINK project when bringing it up to date, since
  722.     THINK C will automatically be made aware whenever you change
  723.     a source file with EnterAct—and all of EnterAct’s best features,
  724.     such as info display and hyperlinking, will be available within
  725.     THINK C. For the details, see Appendix 4.
  726.  
  727. >    Using EnterAct as CodeWarrior's editor
  728.     •    EnterAct sends "touch" events to any open CodeWarrior project,
  729.         so CodeWarrior will be able to keep track of which files need
  730.         recompiling.
  731.  
  732. >    Using EnterAct as a "definition viewer" with other editors:
  733.     •    Have EnterAct with an appropriate project running while
  734.     you use the other editor. Your dictionary should be reasonable
  735.     up to date, and the AutoLook window open
  736.     •    Copy a term in the other editor, and switch to EnterAct
  737.     for instant definition display in the "AutoLook" window
  738.     •    If you don't see an instant definition, try
  739.     <Command><Enter> for spell-tolerant lookup of the clip
  740.     to a separate lookup window
  741.     •    To look up the struct or class containing a copied member
  742.     name, press <Shift><Command><Enter>
  743.     (When looking things up with the <Enter> key, <Command> is
  744.     for Clipboard, and <Shift> is for member lookup -- also called
  745.     "reverse" lookup, so remember "<Shift> into reverse"....)
  746.     
  747. >    Miscellaneous
  748.     •    EnterAct’s “Print” command can print illustrated documents, and
  749.         always folds back long lines rather than clipping them off
  750.     •    “Reformat Selection” lets you clean up plain text documentation,
  751.         including long comments. It was used to maintain this document
  752.     •    “Save As” can be used with projects, so you don’t have to start over
  753.         each time
  754.     •    “Index” commands under the EnterAct menu: function call/called by
  755.     lists, cross-referencing, lists of markers or #included files, and
  756.     “Potential Locals”, which helps ease the declaration of local variables
  757.     (note most of these are for use with C code only, sorry)
  758.  
  759. §    Looking ahead
  760. It would be best at first to focus on building EnterAct projects and
  761. exploiting the various ways of looking up definitions and navigating
  762. around. For the necessary background, read straight ahead here to the
  763. end of the “Browsing” chapter. The one vital new skill to master is
  764. that of pushing the <Enter> key to view definitions, although the
  765. "AutoLook" window will almost always beat you to it.
  766.  
  767. After the “Browsing” chapter, topics become relatively independent.
  768. “Switching to other applications” is recommended reading, since as
  769. mentioned above EnterAct will save documents when you switch out and
  770. refresh them from disk when you switch back, and you should either
  771. agree with this approach or turn this option off. And before starting
  772. in on the “hAWK User’s Manual” on disk, it will help to be familiar
  773. with EnterAct’s approach to multi-file searching, as explained in the
  774. “Searching” chapter. For some fun, check out "§    Code templates" below.
  775.  
  776. For help with any difficulties that might pop up, see the “If there’s
  777. a problem” chapter towards the end of this manual.
  778.  
  779. -    -    -    -    -    -    -    -    -    -    -    -
  780. Getting started
  781. -    -    -    -    -    -    -    -    -    -    -    -
  782. (§)    Installation
  783.  
  784.  
  785.  
  786.  
  787.  
  788.  
  789.  
  790.  
  791.  
  792.  
  793.  
  794.  
  795.  
  796.  
  797.  
  798.  
  799.  
  800.  
  801.  
  802.  
  803.  
  804.  
  805. You’ll find complete instructions for placing the bits and
  806. pieces that make up EnterAct on disk 1 in the file “Installing
  807. EnterAct 3/tt” (which starts up TeachText if you double-click it).
  808.  
  809. There are two different approaches you can take:
  810.     •    drop some aliases into your "EnterAct Stuff" folder
  811.     •    move EnterAct into your compiler folder
  812.  
  813. Recommended, drop aliases of your main development environment
  814. folders (CW, Symantec, MPW etc) into your EnterAct folder. When you
  815. are making a new project and are asked to select a <system> folder,
  816. select the appropriate alias.
  817.  
  818. (§)    What to do first
  819. If you don’t feel comfortable using your Macintosh yet, please take
  820. an hour or so to play with some other program before continuing.
  821.  
  822. The Whirlwind tour will introduce you to the most important things.
  823. After a bit of pushing the <Enter> key and and playing with your new
  824. memory, you’re ready to start using EnterAct seriously—but it wouldn’t
  825. hurt to read the rest of the manual. 
  826.  
  827.  
  828. (§)    Please read these
  829. If you’re a multi–platform developer, please read the section on
  830. “All–or–nothing macro’s” in the “Source code restrictions” chapter.
  831.  
  832. And you should know that EnterAct's default behaviour is to save all
  833. open documents when you switch out, as discussed in “Switching to
  834. other applications”, chapter 20. To avoid this, deselect the
  835. "Safe switching" option at the top of EnterAct's "Options..." dialog.
  836.  
  837.  
  838. (§)    hAWK and Read Resource
  839. After becoming acquainted with EnterAct, add the “hAWK User’s Manual”
  840. and “Read Resource Manual” to an EnterAct project, open them up, and
  841. read along. Learning “Read Resource” takes 5 minutes. Learning to run
  842. a few hAWK programs takes an hour or so,  learning to write them isn’t
  843. that tough—and it’s fun! Adapting your application to call hAWK will
  844. take a day or two. Changing hAWK is harder, but all the source is there.
  845. "hAWK" is a Mac interpreter for "AWK", which resembles C (though
  846. lacking C's more complicated features) with many built-in functions
  847. that let you dash off small programs to do nifty text manipulation.
  848.  
  849. -    -    -    -    -    -    -    -    -    -    -    -
  850. Definitions and conventions
  851. -    -    -    -    -    -    -    -    -    -    -    -
  852. (Note menu commands may appear in quotes here but often are
  853. just capitalized. They are sometimes used as verbs, as in
  854. “when you Balance a comment...”.)
  855.  
  856. Balance: checks all paired delimiters, and detects nested or
  857. improperly–formed comments. If you have an insertion point at the very
  858. beginning of the file, Balance will check the entire file. If there’s
  859. an imbalance, you’ll see where it is. Balance always includes the
  860. delimiters in the shown selection, because to exclude them is stupid.
  861.  
  862. Definition or Entry: for functions and methods, the prototype or
  863. equivalent. For everything else (struct, #define, variable, etc), the
  864. full statement in which the term was mentioned or defined.
  865.  
  866. Dictionary: the collection of terms and definitions for your project.
  867.  
  868. Drag_on Module: a “mini application” packaged as a separate CODE
  869. resource, called as a C function. For instructions and code to call
  870. Drag_on Modules from your application, see the “code to call Drag_ons”
  871. folder on disk 2, and also the example Drag_on caller “Minimal App7”.
  872. While Drag_on Modules require some application to act as a “shell”,
  873. support for all callback functions by the calling application is
  874. optional. Two modules are included: hAWK, a Mac version of AWK (see
  875. “hAWK User’s Manual”) and Read Resource (see “Read Resource Manual”).
  876. If you follow the “Getting started” instructions, both modules will
  877. appear at the bottom of EnterAct’s “EnterAct” menu.
  878.  
  879. Find Definition: given a selected dictionary term, opens the file where
  880. the term is defined and scrolls to the first instance of the term in
  881. the file. The equivalent of <Option>double–click, but in addition works
  882. with full method names, which contain colons.
  883.  
  884. “Go to” link, “Go to” selection: text typically of the form
  885.     file-name marker-name 
  886. where “file-name” is the name of an EnterAct project file and
  887. “marker-name” is the name of a marker in the file, with optional
  888. European-style quotes around either part
  889.     (for example, «MyProj.LOG» «To Do» ).
  890. To open the file and go to the marked position, select the
  891. file-name marker-name text and use the Go to command. Details are in
  892. “‘Go’ commands”, chapter 17.
  893.  
  894. Insertion point: the flashing “|” cursor which marks your place in a
  895. text window when no characters are selected. 
  896.  
  897. Look up a term: to look up a term, select an insertion point just to
  898. the right of it, or double-click on it, and press <Enter>. A lookup
  899. window will appear. The AutoLook window shows definitions automatically
  900. as you type or edit (double-click on the term or click to the right
  901. of it, or type it in).
  902.  
  903. Lookup window: a special kind of text window used to show dictionary
  904. entries. The title begins with “••” or “¶¶”. Often several entries are
  905. “stacked” in one lookup window; to cycle through them, press <Enter>
  906. with a range of characters selected -- or better, hold down the
  907. <Option> key and drag in the window's title bar to pick from a
  908. popup menu.
  909.  
  910. Menu commands are often quoted, always capitalized.
  911.  
  912. Paired delimiters:
  913.     • ()         round brackets, or parentheses
  914.     • []         square brackets
  915.     • {}         braces, or curly braces
  916.     • /* */     comment start and end, together a comment
  917.     • " "         double quotes, around strings (continued across lines with “\”)
  918.     • ' '         single quotes, or ticks.
  919.  
  920. Paste Selection Behind: will Copy the selection in the front window,
  921. switch to the next window, and Paste over what is selected there. The
  922. selection in the next–to–front window will be shown by a two–pixel wide
  923. black border.
  924.  
  925. Project: a three–pane window containing any group of source, header,
  926. plain text, and PICT documents. Selecting Update Dictionary builds a
  927. dictionary for all source and header files. Both the file list and the
  928. dictionary are kept on disk in the corresponding project file.
  929. Double–clicking on a file shown in the project window will both open
  930. the file and send the project window behind all other windows. It can
  931. be brought to the front again with the Windows menu, or
  932. <Command><zero>, if it’s hidden.
  933.  
  934. Range of characters selected: white text on a black background in the
  935. front window, seen for example when you drag over some text. In the
  936. next–to–front window, the selection range is shown outlined in a black
  937. box rather than white on black (the next– to–front window is affected
  938. by Paste Selection Behind, and by some Search commands when the Find
  939. dialog is in front).
  940.  
  941. Recent activity: a full specification of something you’ve done recently
  942. with EnterAct, as presented in the “••Recent Activities” window
  943. generated by the Show Activities command. All significant activities
  944. are recorded, including cut copy paste typing find replace new open
  945. close revert start quit. Recorded details include time, location, and
  946. contents if it was an insert or delete. For details see the “Show
  947. Activities” chapter.
  948.  
  949. Reformat Selection: evens out the line lengths in a range of selected
  950. text, with maximum line length and ragged right versus full
  951. justification as specified in the Options dialog. Intended for use with
  952. comments or plain text, rather than code.
  953.  
  954. Regular lookup: double-click on or click after a term, and press
  955. <Enter>. A lookup window appears, holding all definitions of the term,
  956. or closest matches based on spelling if your spelling was off.
  957. <Option>click in the title bar for a list of definitions.
  958.  
  959. Reverse lookup: select as for regular lookup, but press <Shift><Enter>.
  960. The resulting lookup window holds all struct, union, and class
  961. definitions which mention the word(s) being looked up. <Option>click
  962. in the window's title bar for a list of containing definitions.
  963.  
  964. Sounds-like lookup: select as for regular lookup, but press
  965. <Option><Enter>. Like regular lookup, but not case-sensitive, with
  966. closest matches based on sound rather than spelling. <Option>click in
  967. the resulting lookup window’s title bar for a list of definitions.
  968.  
  969. Specific single keys are placed in <>, eg <Enter>, <Option>, <Return>,
  970. <period>.
  971.  
  972. -    -    -    -    -    -    -    -    -    -    -    -
  973. Whirlwind tour
  974. -    -    -    -    -    -    -    -    -    -    -    -
  975.  
  976. (§)    Hum along
  977. This little tour displays EnterAct’s basic capabilities, to help you
  978. avoid that “lost in space” feeling. However, there is much of potential
  979. interest that is not covered here, so please at least browse through
  980. the rest of the manual afterwards.
  981.  
  982. For an example project we’ll be using “Minimal App7”, the files for
  983. which are included with EnterAct. If you feel adventurous,
  984. substitute your own project for Minimal App below.
  985.  
  986. To exactly follow the tour, you’ll need the files that make up “Minimal
  987. App7”, a minimal application that does nothing but call Drag_on
  988. Modules. The “Minimal App7 ƒ” folder contains the needed
  989. files. If you haven't moved it, it's still in your "EnterAct stuff"
  990. folder.
  991.  
  992.  
  993. (§)    Create a project
  994. We’ll be working with the files that make up “Minimal App7”, and the
  995. first step will be to create a project for it. The project will list
  996. source, header, and documentation files, and also hold a dictionary
  997. of all terms of interest.
  998.  
  999. Let's go! You're probably using EnterAct at this moment, but if not,
  1000. Double–click on the EnterAct icon to start, and cancel the dialogs that appear.
  1001.  
  1002. To make a project for Minimal App7:
  1003.     • pick "New Project" from the EnterAct menu
  1004.     • pick a nice location for your project, and give it a name such as
  1005.     “MinimApp7.e”
  1006.     • click the Save button
  1007.     • in the subsequent dialog that appears, asking you to pick a <system>
  1008.     folder, pick your favorite development environment's folder (CW,
  1009.     Symantec, MPW etc) -- or if you have put an alias for the folder
  1010.     inside your EnterAct folder, pick it instead (IMPORTANT, some
  1011.     development environments contain multiple versions of the toolbox
  1012.     headers -- eg for CW select the "MacOS Support"  folder)
  1013.     • A three–pane project window will appear.
  1014.  
  1015. (§)    Add some files
  1016. You can add files to your project one at a time with the Add Files
  1017. command, and there are are other menu commands to add all files in
  1018. folders, all files in subfolders, and even all files from a list of full
  1019. path names (hold down the <shift> key and look under the EnterAct
  1020. menu for the last two). But we're going to do it the easy way first:
  1021. switch to the Finder, locate the folder called "Minimal App7 ƒ"
  1022. inside your main EnterAct folder, and drag it onto your new project
  1023. window. All files in the folder will be added to your project.
  1024.  
  1025. There is no need to ever select one of the three window panes when
  1026. adding files. The left pane is for your source files (.c), the middle
  1027. for all header files (.h), and the right pane is for all other text
  1028. files (and PICT’s). EnterAct selects the correct pane for each file
  1029. automatically.
  1030.  
  1031.  For our project we’ll also want the toolbox headers and MW or THINK C
  1032.  headers. To add these to your project, hold down the <Shift> key and
  1033.  select Add Mac Headers. All of the standard toolbox headers, and,
  1034.  because of the <Shift> key, all THINK C headers, will be added to the
  1035.  middle (header, or “.h”) pane of your project. If you don't have the
  1036.  THINK C headers, omit the <Shift> key (or ignore any error message).
  1037.  
  1038.  If EnterAct complains that multiple versions of the toolbox headers
  1039.  were found, use the "Select <system> folder" command under the
  1040.  EnterAct menu to select a more specific subfolder within your
  1041.  development environment folder (eg for CW select the
  1042.  "MacOS Support"  folder.
  1043.  
  1044.  And for good measure, use the Add Front File command to add this
  1045.  document to your project.
  1046.  
  1047. At this stage, your project should look something like this:
  1048.  
  1049.  
  1050.  
  1051.  
  1052.  
  1053.  
  1054.  
  1055.  
  1056.  
  1057.  
  1058. ____
  1059.             source pane                    header pane                documentation pane
  1060. ____
  1061.  
  1062. For illustration purposes the project window has been kept small, but
  1063. feel free to make it as large as you like. The project window will go
  1064. to the back when you double-click on a file name to open a file, and
  1065. it can be brought to the front from the Windows menu if it’s hidden.
  1066.  
  1067.  
  1068. (§)    Build a dictionary
  1069. (".c" and ".h" are used as shorthand for source and header below)
  1070. Your dictionary will contain all terms in your .c and .h files that
  1071. are defined or mentioned outside of a function, struct, or union body.
  1072. To build, it, select Update Dictionary from the Project menu, and sit
  1073. back for a few seconds—this shouldn’t take long, typically under 1/2
  1074. second per file on a Mac II. If a major problem or bug does interrupt the
  1075. dictionary build, you’ll see a message telling you what’s up. You can
  1076. either fix it and reselect Update Dictionary, or, with the
  1077. offending file selected in the project window, select Remove File
  1078. followed by Update Dictionary to go on with this tour immediately.
  1079. (See DON'T GIVE UP near line 110 above for fixes to common problems.)
  1080.  
  1081. If you are pursuing your own project instead of Minimal App7, you may
  1082. run out of memory when building your dictionary. If this happens,
  1083. either increase the amount of memory allocated to EnterAct by one Meg
  1084. and try again, or see “EnterAct Memory Needs” on disk 1 for a detailed
  1085. guide to estimating memory needs. Two megabytes can handle a small
  1086. project, but a real whopper may need seven or more.
  1087.  
  1088. (§)    Viewing definitions and prototypes
  1089. If you’re following along with the Minimal App example, open
  1090. “minimalApp7.c” by double-clicking on its name in the left pane of your
  1091. project window. To arrive at the right position for our example, select
  1092. Find from the Search menu, type in "waitnextevent(", click the "Ignore
  1093. case" button,  and then type <Return> or click the OK button until
  1094. you see the following:
  1095.  
  1096.  
  1097.  
  1098.  
  1099.  
  1100.  
  1101.  
  1102.  
  1103.  
  1104.  
  1105.  
  1106. Now is a good time to activate the AutoLook window: first free up some
  1107. room on your screen (a couple of inches at the bottom will do) and
  1108. then select AutoLook from the “EnterAct” menu. It explains itself. For
  1109. a quick look at a definition, either click just after a term or
  1110. double-click on it: the definition will appear instantly in the
  1111. AutoLook window.
  1112.  
  1113. As an AutoLook example, return to the “minimalApp7.c” window and
  1114. double-click on gEvtDetails, on the same line as WaitNextEvent(:
  1115.  
  1116.  
  1117.  
  1118.  
  1119.  
  1120.  
  1121.  
  1122.  
  1123.  
  1124.  
  1125.  
  1126.  
  1127.  
  1128.  
  1129.  
  1130.  
  1131.  
  1132.  
  1133.  
  1134.  
  1135. You will see a definition of gEvtDetails appear immediately in the
  1136. AutoLook window. And, you also see a complete definition of
  1137. EventDetails. 
  1138.  
  1139. As you can see, the AutoLook window resolves variable, struct, and
  1140. typedef tangles to show you all the relevant definitions. It also
  1141. resolves #define’d “aliases” such as “#define H Handle”. For functions,
  1142. you’ll see a prototype, with function name and parameters preselected
  1143. so you can quickly paste a “template” for the function call into your
  1144. code (by switching to the AutoLook window and selecting the command
  1145. Paste Selection Behind). Basically, if the name is defined outside of
  1146. a function body, the AutoLook window will show you the essentials you
  1147. need to  use it. The only requirements are that a file containing a
  1148. definition (or prototype) for the name should be in your project, and
  1149. your dictonary should be up to date for that file.
  1150.  
  1151. As of version 3, EnterAct's AutoLook window will also display
  1152. definitions of local variables, and provide more useful lookup for
  1153. struct and class member names when you double-click on them or
  1154. click after them. For this to work, your file should be a source
  1155. (left pane) or header file, though not necessarily added to your project,
  1156. and you should have your dictonary reasonably up-to-date.
  1157.  
  1158. And AutoLook will also display relevant definitions when you type
  1159. the name of a struct, class, or union member.
  1160.  
  1161. By itself, the AutoLook window can supply most of the details you need
  1162. to program or review nonstop. However, the display in this window is
  1163. transient, keeping up with you as you click or double-click about, or
  1164. type for that matter. To produce a more permanent display of a
  1165. definition or prototype, more work is required on your part: you have
  1166. to press the <Enter> key. To see it work, double-click on EventDetails
  1167. in the AutoLook window, and then press the <Enter> key:
  1168.  
  1169.  
  1170.  
  1171.  
  1172.  
  1173.  
  1174.  
  1175.  
  1176.  
  1177.  
  1178.  
  1179.  
  1180.  
  1181.  
  1182.  
  1183.  
  1184.  
  1185.  
  1186.  
  1187.  
  1188.  
  1189.  
  1190.  
  1191.  
  1192.  
  1193.  
  1194.  
  1195.  
  1196.  
  1197. Your screen may not look exactly like that, but you should see the
  1198. definition of EventDetails appear in a separate window, called a
  1199. “lookup” window.
  1200.  
  1201. A press of the <Enter> key produces a separate window containing the
  1202. information you’re after, definition or prototype.  As you’ll see
  1203. shortly, these separate “lookup” windows can take care of themselves.
  1204. And the “press <Enter>” style of lookup also works when your spelling
  1205. of a term is off, but still “distinctively close”.
  1206.  
  1207. In general, you can look up any function, method, struct class union
  1208. or enum tag, enum constant, typedef, or variable (including low–memory
  1209. and statics) that is defined or mentioned anywhere in your .c or .h
  1210. project files outside of a function, struct, or union body—and any
  1211. #define’d constant or macro that is defined outside of a function body.
  1212. In other words, just about everything of interest except local
  1213. variables or any other “thing” which is meant to be used only within
  1214. a single specific function. Note the AutoLook window does show local
  1215. variables and data members.
  1216.  
  1217. As you’ve seen, the fastest and easiest way to look up a definition
  1218. for a term is to double-click on it with the AutoLook window on-screen.
  1219. You can also click just after the term, or type it, and the AutoLook
  1220. window will keep up. It will also often show class member and
  1221. inline method definitions, after a slight delay.
  1222.  
  1223. However, the AutoLook window has three shortcomings:
  1224.     •    the display lasts only until you look up some other term
  1225.     •    your spelling of the term must be correct
  1226.     •    the display in the AutoLook window doesn’t update as you click about
  1227.         or edit in the AutoLook window itself.
  1228.  
  1229. To overcome these shortcomings, the “press <Enter>” style of lookup
  1230. produces a separate window holding one or more definitions of the term
  1231. being looked up. To look up a term in this way:
  1232.     •    double-click on it, or click just to the right of it, or type it in
  1233.     •    and press the <Enter> key.
  1234.  
  1235. A dictionary entry for the term will appear in a new small text window,
  1236. called a “lookup” window. Lookup windows are mostly like text windows,
  1237. the key differences being that they cannot be directly saved (Copy and
  1238. Paste to a real text window to do that), and they usually can show you
  1239. other dictionary entries. Only one is shown at a time. If your spelling
  1240. is off, the window will show best guesses rather than exact matches.
  1241. (To view other entries, <Option>click in the title bar.)
  1242.  
  1243.  
  1244. (§)    Lookup window frames
  1245. In the small display box along the bottom of the lookup window you will
  1246. see: the name of the file from which the entry was taken; the kind of
  1247. term it is (a one–letter abbreviation, for example “v” for variable,
  1248. “(” for a function, “s” for a struct); and two numbers—the current
  1249. entry you are viewing, followed by the total number of entries
  1250. currently stored in the lookup window. 
  1251.  
  1252. The title of the lookup window will be the term you wanted looked up,
  1253. preceded by two bullets, eg “••EventDetails”. The two bullets are a
  1254. sign that the window is a (temporary) lookup window, not a regular
  1255. document window.
  1256.  
  1257.  
  1258.  
  1259.  
  1260.  
  1261.  
  1262.  
  1263.  
  1264.  
  1265.  
  1266. (§)    Viewing other entries in a lookup window
  1267. A lookup window may hold additional definitions if:
  1268.     •    there are variant definitions of the same term, such as defining
  1269.         and declaring instances of a global variable, or prototype and defining
  1270.         instance of a function
  1271.     •    the same term is used in different ways, such as a struct and a
  1272.         typedef with the same name
  1273.     •    your spelling of the term was incorrect: in this case, closest
  1274.         matches will be shown, and the number shown is under your control.
  1275.  
  1276. Numbers in the display box of the lookup window indicate which entry
  1277. you’re viewing, followed by the number of entries available: if the
  1278. numbers read “1/1”, then only one is present; whereas if the second
  1279. number is greater than one (from “1/2” up to “1/60”) then more entries
  1280. are “stacked up” in the window.
  1281.  
  1282. To view a different entry, hold down the <Option> key and
  1283. click-and-drag in the window’s title bar to select from a popup menu.
  1284. To produce a sample, type "KeyDetails" in any text window and press
  1285. <Enter> to produce a regular lookup window; this term doesn’t match
  1286. anything in the project, so closest matches are shown. From the
  1287. designation “1/4” in the display box, you can tell that four entries
  1288. are contained in the lookup window. To access them, hold down the
  1289. <Option> key, click in the title bar of the “••KeyDetails” lookup
  1290. window, and select from the resulting popup menu:
  1291.  
  1292.  
  1293.  
  1294.  
  1295.  
  1296.  
  1297.  
  1298.  
  1299.  
  1300.  
  1301.  
  1302.  
  1303.  
  1304.  
  1305.  
  1306.  
  1307.  
  1308. You can use <Command> instead of <Option> to view popups if you prefer.
  1309. (Truncated full path names are also shown in the popup menu,
  1310. to help you pick the exact definition you want.)
  1311.  
  1312. Each entry in the popup begins with a one-character “hint” describing
  1313. the definition type, eg “t” for typedef, “v” for variable, “(” for
  1314. function. For a complete list, see “Hints with lookup” in the “Lookup”
  1315. chapter.
  1316.  
  1317. You can also cycle forwards through the entries in a popup window by
  1318. repeatedly pressing the <Enter> key. Press <Option><Enter> to cycle
  1319. backwards. Normally <Option>-clicking in the title bar is handier because
  1320. it gives you an overview of all the entries.
  1321.  
  1322.  
  1323. (§)    The <Enter> key
  1324. In any text window including lookup windows, pressing the <Enter> key
  1325. with an insertion point means “look it up”. The I–beam should be just
  1326. to the right of the term you want looked up. Pressing the <Enter> key
  1327. when characters are selected also activates regular lookup in a
  1328. non-lookup window, and in a lookup window the result of pressing
  1329. <Enter> is either regular lookup or cycling to the next match. In a
  1330. lookup window, if the selection agrees with the name of the term being
  1331. displayed or if your selection is so large that lookup cannot be done,
  1332. then <Enter> will cycle you to the next entry; conversely, if your
  1333. selection is not the name of the definition being shown and your
  1334. selection could be looked up (one word, or two words separated by
  1335. colons) then <Enter> will look up your selection.
  1336.  
  1337. Note that pressing the <Enter> key for separate lookup is meant
  1338. for use with names that are in your dictionary, and in particular
  1339. local variables are not included. To look up the struct or class
  1340. that contains a particular member, press <Shift><Enter> as
  1341. described below.
  1342.  
  1343. Whenever you display a new definition in a lookup window, a selection
  1344. in the window is made for you. Among other things, this selection
  1345. guarantees that if you press <Enter> or <Option><Enter> you will cycle
  1346. back and forth through the definitions, rather than looking something
  1347. up.
  1348.  
  1349. Basically, you don't have to remember anything here since it all comes
  1350. down to intention: if you intend to look up a name, selecting it and
  1351. pressing <Enter> will do just that. If you intend to cycle to the next
  1352. match, pressing <Enter> will do that instead. In the rare case that
  1353. you change the default selection in the window and then wish to cycle,
  1354. either pick from the popup menu or do a Select All before pressing
  1355. <Enter>.
  1356.  
  1357.  
  1358. (§)    Looking up something in a lookup window
  1359. Click to get an insertion point just to the right of the name you want
  1360. looked up, and press <Enter>. With any name except the name of the
  1361. definition currently being shown in the lookup window, you can also
  1362. double-click on the name and press <Enter>.
  1363.  
  1364.  
  1365. (§)    Keeping the lookup around
  1366. You can adjust the maximum number of lookup windows you wish to have
  1367. on–screen at one time, with the Options command: when this limit is
  1368. reached and you press <Enter> to see another lookup, one of the lookup
  1369. windows that is currently on–screen will quietly go away to make room
  1370. for the new one. To prevent this happening to a lookup window that
  1371. you’d like to keep around, select Keep Lookup Around from the windows
  1372. menu while the lookup window is in front. It will then stay on–screen
  1373. until you close it, or until you close the project. When you “keep
  1374. around” a lookup window, the two bullets “••” at the start of the
  1375. window title will change to “¶¶” to help you distinguish the keepers
  1376. from the ones that might go away later.
  1377.  
  1378.  
  1379.  
  1380.  
  1381.  
  1382.  
  1383.  
  1384.  
  1385.  
  1386.  
  1387.  
  1388. (§)    If your spelling is off
  1389. If you press <Enter> for lookup and your spelling did not match any
  1390. term in your dictionary exactly, then you’ll see whatever entries come
  1391. closest, with suppression of variants on the same name in order to
  1392. maximize the variety shown. The entries will be presented in order from
  1393. best match to worst as you press <Enter>. EnterAct is very nearly as
  1394. good at judging what’s close as you are, even though it doesn’t
  1395. “understand” the terms being looked up. This perhaps surprising ability
  1396. results from the natural tendency to give distinctly different names
  1397. to terms with distinctly different meanings. You’ll find more about
  1398. this in the “Lookup” chapter, but EnterAct’s lookup power is sufficient
  1399. that one guideline is all you need: when you’re not sure of the correct
  1400. spelling, type your best guess, remembering that C is case–sensitive.
  1401. EnterAct will almost always retrieve what you want on the first try,
  1402. among the first three entries in the lookup window.
  1403.  
  1404. For an example with Minimal App, see the "KeyDetails" illustrations
  1405. a couple of pages back.
  1406.  
  1407. (§)    Adjusting the number of lookup windows and entries shown
  1408. EnterAct comes preset with a maximum of four lookup windows on–screen
  1409. at one time, and a maximum of four entries per lookup window. You can
  1410. change these limits at any time by selecting the Options command under
  1411. the Edit menu. For complex problems, you may want more lookup windows.
  1412. If your recollection of the spelling of a term has gone out the window,
  1413. you may want to temporarily increase the number of alternate entries
  1414. returned per lookup window. You can vary the number of lookup windows
  1415. from 1 to 10, and the number of entries per window from 1 to 20.
  1416.  
  1417.  
  1418.  
  1419.  
  1420.  
  1421.  
  1422.  
  1423.  
  1424.  
  1425.  
  1426.  
  1427.  
  1428.  
  1429.  
  1430.  
  1431.  
  1432.  
  1433.  
  1434.  
  1435.  
  1436.  
  1437.  
  1438. (§)    Working with lookup windows
  1439. You’ll probably find that the AutoLook window by itself can handle more
  1440. than half of your information retrieval needs. And often you’ll want
  1441. to have more permanent separate lookup windows showing data structures
  1442. that you’re working with for more than a moment, and transient lookup
  1443. windows to supplement the AutoLook display. Separate lookup windows
  1444. are generated by double-clicking on or clicking after a name and
  1445. pressing the <Enter> key, and made permanent by selecting Keep Lookup
  1446. Around (the key equivalent <Command><K> is a good one to memorize).
  1447.  
  1448. To help you manage lookup windows EnterAct places, sizes, scrolls, and
  1449. makes selections in them for you, and also closes old lookup windows
  1450. to make room for new ones. But the lookup windows have to go somewhere
  1451. on your screen(s), and you’ll find the lookup process goes more
  1452. smoothly if you leave some screen area free for the lookup windows to
  1453. occupy. How much room you leave for lookup windows is best judged by
  1454. experience, and will vary according to the needs of the moment. Some
  1455. things to keep in mind:
  1456.     •    lookup windows ignore the project window when looking for a place
  1457.         to appear
  1458.     •    lookup windows prefer to occupy a small place rather than cover one
  1459.         of your working windows
  1460.     •    if some window has to be covered by a lookup window, the lookup
  1461.         window will try to avoid your front two windows
  1462.     •    lookup windows will try to appear right next to your front window,
  1463.         preferably below or above it.
  1464.  
  1465. (§)    Reverse lookup (<Shift><Enter>)
  1466. On occasion you may find yourself viewing a member name and wondering
  1467. what struct, union, or typedef contains it. Quite often, the AutoLook window
  1468. will immediately display the definition you want. If not, double-click
  1469. on or click after the member name and press <Shift><Enter> to invoke
  1470. EnterAct's "reverse lookup".
  1471.  
  1472. Here’s the result of double-clicking on "ioFDirIndex" and pressing
  1473. <Shift><Enter>:
  1474.  
  1475.  
  1476.  
  1477.  
  1478.  
  1479.  
  1480.  
  1481.  
  1482.  
  1483.  
  1484.  
  1485.  
  1486.  
  1487.  
  1488.  
  1489. (Note pressing just <Enter> would have produced the definition
  1490. of ParamBlockHeader, not a list of structs or classes that
  1491. contain it)
  1492.  
  1493. As with all lookup windows, you can access the other definitions
  1494. stacked up in it by holding down the <Option> key and clicking in the
  1495. title bar to choose from a popup menu. 
  1496.  
  1497. Reverse lookup is not case-sensitive. Although it is called “struct
  1498. for member”  lookup elsewhere, it is actually slightly more, since it
  1499. attempts to match your selection with something in a struct, union,
  1500. or typedef without regard for whether it is a member name. Reverse
  1501. lookup accepts arbitrary strings of text up to 255 characters (for this
  1502. you’ll have to select the text to be looked up and then press
  1503. <Shift><Enter>) and will match it against anything in a definition,
  1504. even inside a comment. Aside from being case-insensitive, reverse
  1505. lookup requires exact spelling—but your selection can be just part of
  1506. a word, or several words with punctuation included.
  1507.  
  1508. The AutoLook window will usually show struct-for-member
  1509. lookup for a term. If you're inside a function in a source file then
  1510. AutoLook will be on average more accurate at providing the correct
  1511. definition. In any case, only the first containing struct or class will be
  1512. shown. This lets you see prototypes for inline method definitions that are
  1513. entirely contained in a class definition, and "fDataMembers", as
  1514. well as regular struct definitions for some member.
  1515.  
  1516.  
  1517. (§)     “Sounds like” (phonetic) lookup
  1518. The situation: “I’m desperate, show me a definition even if it’s wrong,
  1519. all I can tell you is the name sounded something like this:”. The
  1520. answer: type your guess and press <Option><Enter>. Your guess will be
  1521. boiled down to a string of standard consonants, then compared with
  1522. boiled-down versions of all your dictionary terms, and you’ll be shown
  1523. the best matches. <Option><Enter> is not case-sensitive (it's only
  1524. barely vowel-sensitive), and should be kept in mind as an
  1525. emergency backup, for those rare occasions when regular lookup gives
  1526. up on you.
  1527.  
  1528. (§)    Seeing where a term is defined
  1529. The simple way is to <option> double-click on the term. To jump to the
  1530. definition of a scoped name such as "thisClass::thatMethod()",
  1531. <option>double-click on one of the names without releasing the mouse
  1532. after the second click. drag over to include the other name, and let go.
  1533.  
  1534. The "Find Definition" command does the same thing as <option>
  1535. double-click, but also lets you select part of a word, such as just
  1536. the "WindowData" part of "WindowDataPtr", before jumping away.
  1537.  
  1538. As a Minimal App example, open a new window if you haven’t done so,
  1539. type "gacc" , and <Option> double-click on it:
  1540.  
  1541.  
  1542.  
  1543.  
  1544.  
  1545.  
  1546.  
  1547.  
  1548.  
  1549.  
  1550.  
  1551.  
  1552.  
  1553. You’re viewing the definition of the static variable gacc , which is
  1554. used for communicating with Drag_on Modules. You will also be able to
  1555. jump to the definitions of static functions, #define’s, struct, union,
  1556. enum, and class tags, enum constants, typedef’s, methods—in other
  1557. words, anything defined at the top level in your source files.
  1558.  
  1559. If a member name is unique (used only in one struct, class, or
  1560. union) you can <option>double-click on it reliably.
  1561.  
  1562. If you can’t jump to a definition because your spelling is wrong, first
  1563. look up the correct spelling first by clicking after the name and
  1564. pressing the <Enter> key. Then, you can <option> double-click on the
  1565. correctly-spelled name right in the lookup window.
  1566.  
  1567. For the special case of multiple definitions of a term (eg several static
  1568. variables with the same name), you need to tell EnterAct which one you
  1569. want, and the way to do that is to do your <option>double-click in a
  1570. lookup window that is displaying the exact definition you want. So
  1571. the sequence is:
  1572.     •    look the name up (select it, press <Enter>)
  1573.     •    use the lookup window's popup menu to find the exact definition
  1574.         you want (<option>click in the window's title bar, and look at the
  1575.         truncated full path names shown beside each instance)
  1576.     •    after picking the one you want from the popup menu, double-click
  1577.         on the term and off you go.
  1578.  
  1579. Doing your <option>double-click in the AutoLook window won't work
  1580. reliably with terms that have multiple definitions.
  1581.  
  1582. If you're mildy annoyed at this point, use just the AutoLook
  1583. window for a while, it will cheer you up.
  1584.  
  1585. (§)    Balance
  1586. Balance checks all of the paired delimiters in C (with the picky
  1587. exception of angle brackets <>). If you select an insertion point at
  1588. the top of a file (with <Option><up arrow>, or Go to Top), Balance will
  1589. balance your entire file. If any error in balance is detected, you’ll
  1590. be shown the mismatched or unmatched delimiter. When balancing a file,
  1591. if you hear a beep and the insertion point remains at the top of the
  1592. file, that means your whole file balanced.
  1593.  
  1594. As a shortcut, you can double-click on a delimiter.
  1595.  
  1596. Balance also detects nested comments, and more importantly any single
  1597. failure to properly start or end a comment, something even most
  1598. compilers don’t do. Since EnterAct’s dictionary–builder checks comments
  1599. fully, simply by building the dictionary you will guarantee that no
  1600. improper comment in any of the included source files will ever generate
  1601. a wild pointer or an uninitialized variable.
  1602.  
  1603. If your source code deliberately contains nested comment starts, select
  1604. the Options command and uncheck the “Detect nested comment starts” box
  1605. in the "Parse" panel.
  1606.  
  1607. (§)    Searching
  1608.  
  1609.  
  1610.  
  1611.  
  1612.  
  1613.  
  1614.  
  1615.  
  1616.  
  1617.  
  1618.  
  1619.  
  1620. The Find dialog in EnterAct is modeless, which means that when the Find
  1621. dialog is in front any search command you pick will apply to the window
  1622. just behind it. An important exception is Replace All, which works only
  1623. when a text window is in front. 
  1624.  
  1625. The "Find" button in the dialog is the exact equivalent of the
  1626. "Find Again" menu command. Both can be used with the project
  1627. window itself by the way, to find file names in long lists.
  1628.  
  1629. A popup menu at the top of the Find dialog remembers the 20 most recent
  1630. strings of characters that you have searched for.
  1631.  
  1632. The little buttons in the lower–right of the Find dialog allow to to
  1633. set up a “coarse” multi–file search of your project files. As you click
  1634. them, you’ll see bullets appear beside files to be searched in your
  1635. project window. 
  1636.  
  1637. If you click the "Batch" check box, your multi-file search will be
  1638. done all at once, and the results presented in a text window
  1639. (file name, line number, and the full line where found). To go to
  1640. a particular found instance, click on the line and use "Go to...".
  1641.  
  1642. To “fine–tune” your multi–file selection, hold down the <Option> key
  1643. and click on or drag over the file names right in the project window.
  1644. Try it out now by clicking and dragging in your project window with
  1645. the <Option> key down and you’ll see that it acts as a toggle,
  1646. selecting files if they were not selected and vice versa. Your
  1647. multi-file selection can also be used with the Remove •'d Files
  1648. command, and as input to a hAWK program (which makes setting up a
  1649. program run a trivial thing).
  1650.  
  1651.  
  1652.  
  1653.  
  1654.  
  1655.  
  1656.  
  1657.  
  1658.  
  1659.  
  1660.  
  1661.  
  1662.  
  1663.  
  1664.  
  1665.  
  1666. (§)    Adding marks to a source file
  1667. EnterAct's default behaviour is to automatically provide marks for
  1668. all functions, methods, structs and classes in a source or header
  1669. file, to append a brief summary of arguments for all functions
  1670. and methods, and to not save the marks with the source or header
  1671. file. For documentation, EnterAct does no automatic marking but
  1672. does save any marks that you add manually when you save the
  1673. file. Normally this is all you need.
  1674.  
  1675. To access the popup menu listing marks for a file, hold down the
  1676. <Option> or <Command> key and click-and-drag in the title bar of the
  1677. file’s window. Just select a mark and off you go.
  1678.  
  1679. EnterAct’s markers are compatible with THINK C and MPW, indeed the
  1680. suspicion is that there is only one kind of marker in the universe.
  1681.  
  1682. Markers can be added “manually’” to a document, most commonly to
  1683. mark section or chapter headings in your documentation. For an example,
  1684. see the online version of this manual, or the “hAWK User’s Manual”.
  1685. For the details on markers, please see the
  1686. «18   Markers and the Locations menu» chapter.
  1687.  
  1688. The "Automark" command under the Search menu provides some
  1689. additional options. But the slight advantage of being able to
  1690. mark additional points in your source file is usually outweighed
  1691. by the nuisance of having to use the "Automark" command when
  1692. you change the file. See the «18   Markers and the Locations menu»
  1693. chapter for details, but I'd recommend against using the
  1694. "Automark" command in its present form. If you would really like
  1695. a more useful version of this command, let me know
  1696. (kearle@interlog.com). Here's what the dialog looks like:
  1697.  
  1698.  
  1699.  
  1700.  
  1701.  
  1702.  
  1703.  
  1704.  
  1705.  
  1706.  
  1707.  
  1708.  
  1709.  
  1710.  
  1711.  
  1712. (§)    Going to markers in other files
  1713. As an aid to linking source files with supporting documentation,
  1714. EnterAct gives you a way to jump to a marker in any project file. This
  1715. is done by selecting text in any window that consists of a project file
  1716. name followed by a marker name, and then issuing the "Go to..." command.
  1717.  
  1718. EnterAct can generate the necessary file name and marker name for the
  1719. link, as follows:
  1720.     •    in the window for the document in whch the marker is defined, access
  1721.         the marker menu and pick the mark, but in addition to holding down the
  1722.         <Option> or <Command> key hold down the <Shift> key as well
  1723.     •    the necessary text will be placed on the clipboard, ready for
  1724.         pasting. The file name and marker name will each be surrounded by «»
  1725.         quotes, which are optional but help the text to stand out.
  1726.     •    since you ended up at the mark's location as a side-effect, you
  1727.         can get back to your original location in the file by using the
  1728.         Go Back command.
  1729.     •    to generate the text for all markers in one or more files, you
  1730.         can use the "Index Marker Names..." command (chapter 22). However,
  1731.         this works well only with documentation, since the marks for
  1732.         source and header files are by default not saved.
  1733.  
  1734. A typical “Go to” link looks like
  1735. ____
  1736.     /* See «EnterAct 3 Manual» «13   Documents and windows» */
  1737. ____
  1738. and if the file “EnterAct 3 Manual” has been added to your current project
  1739. then you can jump to the marker named “13   Documents and windows” by
  1740. clicking anywhere on the line and using the "Go to..." command.
  1741.  
  1742. The advantage of this kind of link is that since the marker position
  1743. is maintained as you edit, so is your link. With this
  1744. «file name»«marker name» style of link, both file and marker name can be
  1745. abbreviated, and the link is immune to minor variations in spelling.
  1746.  
  1747. Many variations on “Go to” are available, such as going to a file-name
  1748. line-number, or just a file name, marker name, or line number. For
  1749. details, see the “‘Go’ commands” chapter.
  1750.  
  1751.  
  1752. (§)    Keeping track of things
  1753. When you close a project, it remembers which project text files you
  1754. have open. Later, when you reopen the project, those text files are
  1755. reopened as well. This makes it a little easier to pick up where you
  1756. left off. You could call this “context restoration”, though some like
  1757. to call it the “painless Quit”. It’s all automatic—just close the
  1758. project before you close your working files, or if you’re quitting,
  1759. don’t bother to close your working files first.
  1760.  
  1761. The concept of “undo” takes a step forward with EnterAct’s Show
  1762. Activities command, which displays the last 10,240 things you have done
  1763. with EnterAct. Descriptions are in plain English, and full contents
  1764. of edits are shown. A typical entry looks like this:
  1765. ____
  1766.  
  1767. ¶45
  1768. Tue, Mar 9, 1993 7:45:11 pm TYPING «Untitled-1» 1 1 (obs)
  1769. =>inserted 15 characters:
  1770. «AdjustTheCursor»
  1771. ¬
  1772.  
  1773. ____
  1774. —where “«Untitled-1» 1 1 (obs)” means the action started in the
  1775. “Untitled-1” window at line 1, character 1 on the line (ie the start
  1776. of the file), and the typing is now “obsolete”, ie it was never saved
  1777. to disk before closing the window. The “file name - line number” part
  1778. of the activity record is compatible with EnterAct’s “Go to” command.
  1779. And the full contents of all inserts and deletes are shown, up to a
  1780. very large limit. By using "Go to" and the contents of the activity
  1781. record you will be able to locate and selectively undo any of your
  1782. recent activities, provided that you haven’t destroyed the context of
  1783. the edit with a huge delete or by erasing the corresponding file. To
  1784. help you locate the edit position, Show  Activities provides the option
  1785. of correcting the original positions of edits to reflect the effects
  1786. of other edits, which is normally what you’ll want when reviewing or
  1787. selectively undoing your recent activities.
  1788.  
  1789. Since there are new concepts here, the “Show Activities” chapter goes
  1790. into considerable detail on such topics as “obsolete edits” and
  1791. “updated activity positions”. Once you’ve read through it, you’ll
  1792. realize you knew most of it already—you just didn’t talk about it much
  1793.  
  1794. EnterAct saves your activities to a disk log as you work. So “undo”
  1795. capabilities are not lost just because you quit and restart.
  1796.  
  1797. There is a way to undo files (one at a time) back to specific
  1798. activities. This involves the use of a hAWK program, and you’ll find
  1799. the details in the “Show Activities” chapter. If you anticipate needing
  1800. to do this, I would recommend using some sort of real version control
  1801. rather than EnterAct to revert a file to a previous state.
  1802.  
  1803. Though you haven’t done much yet, it wouldn’t be a bad idea to call
  1804. up the Show Activities dialog, pick any old options, click the OK
  1805. button, and see what happens. Not something you’ll use every day, but
  1806. your last ten thousand activities are still there if you need to review
  1807. or undo them, or figure out what the heck you just did.
  1808.  
  1809.  
  1810. (§)    Classes and methods
  1811. When you build yourself a project that contains classes, try out the
  1812. Browse command to see a graphic view of your classes. Double–click on
  1813. a class name to view the class definition, click–and–hold briefly on
  1814. a class name to select from a list of methods, and then view the method
  1815. definition. If you’re new to C++ or Java, you’ll find no better
  1816. way to learn than by exploiting EnterAct’s project–building, lookup,
  1817. and browsing power—in fact, you might want to build a project for a
  1818. TCL or PowerPlant demo or somesuch right now.
  1819.  
  1820.  
  1821.  
  1822.  
  1823.  
  1824.  
  1825.  
  1826.  
  1827.  
  1828.  
  1829.  
  1830.  
  1831.  
  1832.  
  1833.  
  1834.  
  1835.  
  1836.  
  1837.  
  1838.  
  1839.  
  1840.  
  1841.  
  1842.  
  1843.  
  1844.  
  1845.  
  1846.  
  1847. (Color is recommended for viewing the browser)
  1848.  
  1849. (§)    Little things worth knowing
  1850. If you hold down the <Option> key while clicking in the zoom box of
  1851. a window, only the length will be zoomed. Without covering up your
  1852. AutoLook window.
  1853.  
  1854. When you double–click on a file in the project window to open the file,
  1855. the project window will retreat behind all other windows. You can bring
  1856. it to the front with <Command><zero>. Even on small screens this allows
  1857. you to have a large project window and use it conveniently as a “mini
  1858. Finder”.
  1859.  
  1860. Paste preserves relative indentation, at least in the commonest
  1861. situations where you would want your indentation to be retained( see
  1862. the “Paste preserves indentation” section in the “Editing” chapter).
  1863.  
  1864. Windows remember their last saved location, unless you select otherwise
  1865. from the Options dialog. 
  1866.  
  1867. EnterAct takes special care of your text documents, ensuring
  1868. that disk files are updated when you leave EnterAct, and windows
  1869. are updated when you return to EnterAct (see “Switching to other
  1870. applications”). This is the default behaviour. You can turn off the
  1871. automatic saving and restoring if you want--but keep in mind that
  1872. the "Show Activities..." command can show you the last 10,000
  1873. things you did, in the rare case where you chop something important
  1874. out of a file and then switch out.
  1875.  
  1876. Reformat Selection is handy for making comments pretty again after
  1877. you’ve chopped them up (it’s undoable, and some options are available
  1878. in the Options dialog). 
  1879.  
  1880. There are some other things worth trying out, such as full Drag and Drop
  1881. for text, code templates, Dual Batch Find -- hey, take a browse through
  1882. the rest of the manual when you have a minute.
  1883.  
  1884.  
  1885. (§)    Source code restrictions (don't panic)
  1886. There are three sorts of code constructions that are nominally correct,
  1887. but throw off EnterAct’s dictionary–builder. Please read the next
  1888. chapter "Source code restrictons" if the very notion bothers you.
  1889. Or just go ahead and use EnterAct, but remember that if you do
  1890. run into a problem while building your dictionary there are simple
  1891. workarounds for all problems in the "Source code restrictons" chapter.
  1892.  
  1893.  
  1894. (§)    Onwards
  1895. If you’ve tried things out for yourself while taking this tour, I
  1896. expect you know enough about EnterAct to begin using it full–time for
  1897. code creation and review—aside from knowing when to poke the <Enter>
  1898. and <Option> keys, there isn’t much to the basics. Eventually, alas,
  1899. you should probably read the rest of the manual. Personally, I enjoy
  1900. reading manuals.
  1901.  
  1902. To acquaint yourself with hAWK and Read Resource, add the “hAWK
  1903. User’s Manual” and “Read Resource Manual” to an EnterAct project and
  1904. follow the instructions therein. Learning Read Resource is a 5 minute
  1905. job. hAWK is rather more complicated, but it’s a powerful, widely–used
  1906. little language and learning it should prove well worth the effort.
  1907. Running hAWK programs is easy, at least, and many useful programs are
  1908. included.
  1909.  
  1910.  
  1911. -    -    -    -    -    -    -    -    -    -    -    -
  1912. Source code restrictions (ayeee! I knew it!!) - don't panic
  1913. -    -    -    -    -    -    -    -    -    -    -    -
  1914. §    Why not just compilable code?
  1915. EnterAct is able to identify terms in your code and correctly deduce
  1916. the type and definition of each term without doing extensive
  1917. preprocessing or semantic analysis. The benefits are lightning speed,
  1918. considerable tolerance of first–draft errors, and full information
  1919. retrieval, definition finding, browsing, and automatic marker placement
  1920. available right from the beginning of the code creation process. This
  1921. is all made possible with EnterAct’s Heuristic Adaptive Reentrant
  1922. Parser, which is based on a description of the way people actually
  1923. write code and the importance they attach to various constructs,
  1924. rather than on the textbook prescription. The drawback is that EnterAct
  1925. cannot deal with absolutely everything that is possible in C/C++/Java, and
  1926. some minor restrictions must be satisfied in order for the
  1927. dictionary–builder to deal properly with your code.
  1928.  
  1929. In practice, only the “illegal aliases” will present a significant
  1930. problem if present, in that the only workaround is to remove them
  1931. (have you ever seen one? me neither...).
  1932. Obviously-unnecessary parentheses will result in extra or missing
  1933. dictionary entries for some terms. Troubles with aliases and
  1934. parentheses are extremely rare, since they obfuscate the source code
  1935. for beginner and expert alike. To overcome problems with nested comment
  1936. starts or “all-or-nothing macro’s”, you just need to make EnterAct
  1937. aware that they are present, as explained below.
  1938.  
  1939.  
  1940. §    Aliases
  1941. Defined equivalents for certain keywords and punctuation should be
  1942. avoided. A defined equivalent or alias takes the form
  1943. ____
  1944.     #define    Record     struct
  1945. ____
  1946. for example. EnterAct won’t know that “Record” is supposed to mean
  1947. “struct”, and the dictionary–builder won’t work well at all.
  1948.  
  1949. Keywords that should not be aliased:
  1950. ____
  1951.     asm        enum        pascal        Pascal        struct        typedef    
  1952.     union        void        class
  1953. ____
  1954.  
  1955. Punctuation that should not be aliased:
  1956. ____
  1957.     ;    :    ,    \    "    '    {}    ()    []    /    *    =
  1958. ____
  1959.     
  1960. You will never see aliases for any of these in published code, or in
  1961. any code intended to be read by more than one person, for the simple
  1962. reason that such a creature as
  1963. ____
  1964.     Record fileData BEGIN int x SEMI END SEMI
  1965. ____
  1966. would be rather difficult for anyone but the author to read.
  1967. Other aliases, such as
  1968. ____
  1969.     #define    EQ    ==
  1970. ____
  1971. are perfectly OK, by the way.
  1972.  
  1973. §    Obviously unnecessary parentheses
  1974. These are just as rare as the aliases above. This restriction applies
  1975. only outside of function bodies and refers only to parentheses that
  1976. would result in a variable declaration resembling a function
  1977. declaration. An example would be
  1978. ____
  1979.     Peter    (Harvey);
  1980. ____
  1981. Right now you know as much as EnterAct does when it runs into this sort
  1982. of thing—is it a variable declaration or a function declaration? You
  1983. may have deduced that the above declaration is almost certainly for
  1984. a function “Peter” returning an (implicit) int, since you would never
  1985. type those parentheses in a simple variable declaration,
  1986. ____
  1987.     int    (x);
  1988. ____
  1989. —these are an example of what is meant by “obviously unnecessary
  1990. parentheses”, namely parentheses that make the code harder to read,
  1991. not easier. If you avoid these excessive parentheses when declaring
  1992. variables outside of a function, that’s all that’s needed. Once again,
  1993. you won’t see them in any published code, and even beginners feel that
  1994. such parentheses make life harder, not easier.
  1995.  
  1996.  
  1997. §    Nested comment starts
  1998. This refers to two consecutive comment starts with no intervening
  1999. comment end, eg
  2000. ____
  2001.     /*#define    DEBUG    /* some comment here */
  2002. ____
  2003. where the intent is to define or undefine DEBUG by removing or
  2004. replacing the first comment start. If your code employs this (lazy)
  2005. sort of construct, then instruct EnterAct that this is not an error
  2006. by selecting Options… from the Edit menu and removing the check mark
  2007. from the box titled “Detect nested comment starts”. There is an
  2008. illustration of this in the “Options” chapter, by the way. As a
  2009. side-effect, EnterAct will not be able to warn you if a comment end
  2010. has accidentally been omitted.
  2011.  
  2012. If you value the notion that EnterAct can fully trap any single failure
  2013. to properly start or end a comment (something that many compilers,
  2014. including THINK C, don’t do), then leave the check mark in the  “Detect
  2015. nested comment starts” box, and remove the nested comment starts from
  2016. your code. Simplest, use "//" style comments instead.
  2017.  
  2018. §    Preprocessor tangles
  2019. Although these do pop up, they're easy to fix up. 
  2020.  
  2021. Conditional #defines which duplicate important punctuation can
  2022. cause trouble, such as
  2023. ____
  2024.     #ifdef GO_LONG
  2025.     long GetArrayIndex(void) {
  2026.     #else
  2027.     short GetArrayIndex(void) {
  2028.     #endif
  2029. ____
  2030. —EnterAct will complain about the '{' being there twice, and
  2031. the simple fix is to put the curly brace (which isn't conditional
  2032. anyway) after the conditional part:
  2033. ____
  2034.     #ifdef GO_LONG
  2035.     long GetArrayIndex(void)
  2036.     #else
  2037.     short GetArrayIndex(void)
  2038.     #endif
  2039.     {
  2040. ____
  2041.  
  2042. EnterAct's parser can sometimes spazz out because it's trying to
  2043. handle C and C++ and first-draft code and all possible values of
  2044. a #define all at once. For example,
  2045. ____
  2046.     typedef struct A
  2047.     #ifdef __cplusplus
  2048.     : public B
  2049.     #endif
  2050.     {
  2051. ____
  2052. used to generate a complaint, and there may still be similar constructs
  2053. out there that cause a problem. The fix is to provide the full C and
  2054. C++ introductions separately, as in
  2055. ____
  2056.     #ifdef __cplusplus
  2057.     struct A : public B
  2058.     #else
  2059.     typedef struct A
  2060.     {
  2061. ____
  2062.  
  2063. And one more tangle: if you put something that's deliberately
  2064. uncompilable in your code, avoid all punctuation except commas
  2065. and semicolons (some few others might work). For example,
  2066. ____
  2067.     #ifdef A_Compiler
  2068.     #ifdef B_Compiler
  2069.     error - won't you please make up your mind?!
  2070.     ...
  2071. ____
  2072. would trip EnterAct, whereas
  2073. ____
  2074.     #ifdef A_Compiler
  2075.     #ifdef B_Compiler
  2076.     error, please make up your mind
  2077. ____
  2078. while lacking punch, would work fine from EnterAct's view.
  2079.  
  2080. §    All–or–nothing macro’s
  2081. This final restriction is one that you may run into, but the workaround
  2082. is easy.
  2083.  
  2084. An “all–or–nothing” macro is a macro that looks something like
  2085. ____
  2086.     #ifdef        BLUETREECOMPILER
  2087.     #define P(x)     x
  2088.     #else    /* some other compiler */
  2089.     #define P(x)
  2090.     #endif
  2091. ____
  2092. —so P(x) either does nothing at all to its argument or it “eats” the
  2093. argument, but either way the macro itself disappears from the code.
  2094. If such a macro is the very first thing in a statement then EnterAct
  2095. will deal with it correctly, for example "P(typedef  int  INT16;)"
  2096. would result in INT16 being recorded as a typedef’d equivalent of
  2097. “int”. 
  2098.  
  2099. However, if the all–or–nothing macro is not the very first thing in
  2100. the statement, as in
  2101. ____
  2102.     int myFunc P((int x, long y));
  2103. ____
  2104. then EnterAct will mistakenly record “P” and not “myFunc” as the
  2105. function name, and in general it will misrecord any similar statement
  2106. where an–or–nothing–macro isn’t the first thing in the statement.
  2107.  
  2108. In case you’re wondering, the intention of
  2109. ____
  2110.     int myFunc P((int x, long y));
  2111. is to produce either
  2112.     int myFunc (int x, long y);
  2113. or
  2114.     int myFunc ();
  2115. ____
  2116. —in other words either a proper modern prototype or an old–fashioned
  2117. declaration, and this sort of thing is useful when writing code that
  2118. will be compiled using different compilers.
  2119.  
  2120. What to do? Call up the Macro's to skip dialog from the EnterAct menu,
  2121. and enter the name of the macro there.
  2122.  
  2123. (PLEASE NOTE you may not realize you have an all-or-nothing macro until
  2124. after you have built your dictionary. If this is the case, you should
  2125. completely rebuild your dictionary to ensure that all definitions are
  2126. correct. To completely rebuild your dictionary:
  2127.     •    hold down all three of the <Shift>, <Option>, and <Command> keys
  2128.         while using the mouse to select Update Dictionary from the EnterAct
  2129.         menu.
  2130.  
  2131. )
  2132.  
  2133.  
  2134.  
  2135.  
  2136.  
  2137.  
  2138.  
  2139.  
  2140.  
  2141.  
  2142.  
  2143.  
  2144.  
  2145.  
  2146.  
  2147.  
  2148.  
  2149.  
  2150.  
  2151.  
  2152.  
  2153.  
  2154. (This button reads “New projects” if no project is open at the time.)
  2155.  
  2156. -    -    -    -    -    -    -    -    -    -    -    -
  2157. Projects
  2158. -    -    -    -    -    -    -    -    -    -    -    -
  2159. §    Introduction
  2160. Any collection of TEXT or PICT files from up to 6 disks can be added
  2161. to an EnterAct project. The project window displays three lists of
  2162. files in your project, and behind the scenes your project contains a
  2163. dictionary of C/C++/Java term definitions, prototypes, and general notes.
  2164. To create and make use of a project:
  2165.     •    use New Project to create an entirely new project, or use Save As
  2166.         with a project window in front to build on an existing project
  2167.     •    if you have nonstandard file extensions (beyond the usual
  2168.         .c, .h, .cp etc) use the "File Extensions..." dialog to make your
  2169.         project aware of them
  2170.     •    add files to your project, the easiest way being to drag folders
  2171.         or files or aliases onto your project window (note there is no
  2172.         need to select a pane)
  2173.     •    bring your dictionary up to date with Update Dictionary
  2174.     •    pick AutoLook from the EnterAct menu
  2175.     •    thereafter, bring your dictionary up to date whenever you want your
  2176.         dictionary to reflect new or altered definitions.
  2177.     •    to switch to a different project that you've had open recently,
  2178.         <Option> or <Command> click in your current project window's
  2179.         title bar to pick from a popup list (please see "Switching to
  2180.         other projects" below -- <Option>clicking will close all your
  2181.         text windows, whereas <Command>clicking will not)
  2182.     •    things work best if you include definitions for all the
  2183.         names in your source code, especially toolbox terms but also
  2184.         PowerPlant or TCL, and ANSI headers.
  2185.  
  2186. NOTE if a folder's name is in parentheses, the files in it will not
  2187. be added to your project. To exclude a folder such as "Old Source",
  2188. change its name to "(Old Source)".
  2189.  
  2190. The three lists of files in the project window can be used to open
  2191. files, by double-clicking on the file names listed there. You can set
  2192. up a multi-file selection by holding down the <Option> key and clicking
  2193. on or dragging over file names, or select all files of a certain type
  2194. by using the buttons in the Find dialog. Bullets (•) will appear beside
  2195. selected files. This list of files can be used with multi-file
  2196. searching or passed as input to a hAWK program or one of the
  2197. “Index” commands under the EnterAct menu. You can also remove
  2198. the selected files from the project with Remove •'d Files.
  2199.  
  2200. To exclude a file from being built into your dictionary, hold down the
  2201. <Command> key and click on its name (more on this later).
  2202.  
  2203. Other things you can do with the lists of project files:
  2204.     •    Find all or part of a file name (useful with enormous lists, have
  2205.         the project window in front and select the appropriate list before
  2206.         using Find or Find Again)
  2207.     •    Copy a selected file name
  2208.     •    use the up and down arrows to move up and down the file lists, and
  2209.         the left and right arrows to change panes
  2210.     •    type your way to a particular file in a pane, by typing the first part
  2211.         or any distinctive part of the name (priority given in that order)
  2212.     •    open a file by selecting it and issuing the “Go to” command
  2213.  
  2214. The project window goes to the back whenever you open a file from it,
  2215. and is listed under the Windows menu as the first file. Any project
  2216. files that you have open when you close a project are remembered, and
  2217. reopened as you left them when you reopen the project.
  2218.  
  2219. The dictionary is required by regular lookup (click just after a term
  2220. name and press the <Enter> key), and by the AutoLook window which
  2221. displays definitions and prototypes automatically as you edit or mouse
  2222. around. More on this later, of course.
  2223.  
  2224. Only one project can be open at a time. You don’t need to have a
  2225. project open to use EnterAct as an editor.
  2226.  
  2227.  
  2228. §    Project files
  2229. An EnterAct project can track any set of TEXT or PICT files. The source
  2230. and header files don’t have to add up to a compilable
  2231. application—anywhere from one file to part or all of the source and
  2232. documentation for several applications can be an EnterAct project. The
  2233. only practical limit is available memory, since your entire dictionary
  2234. is kept in memory: allow EnterAct 7 Meg if you can, otherwise you
  2235. may have to delete some of the larger unneeded header files from
  2236. your project.
  2237.  
  2238. An EnterAct project can contain files from up to 6 disks. If your
  2239. project files are split across several disks, you should have all the
  2240. disks on–line (mounted) before updating your dictionary or doing things
  2241. with a multi–file selection. EnterAct tracks your disks by name, and
  2242. many other applications do the same, so please ensure that all your
  2243. disks have different names. If you ever find it necessary to move a
  2244. considerable number of files from one folder or disk to another, the
  2245. simplest way to deal with the change in any EnterAct project that
  2246. refers to those files is to throw the project away and create an new
  2247. one. Or, you can use Remove •'d Files (<Option>drag over the file names
  2248. first in the project window so that bullets (•) appear to the left of
  2249. the names) followed by Add Files and then Update Dictionary afterwards
  2250. to update your project. And a third way, slightly more complicated:
  2251.     •    before moving the files, select all files for multi-file ops
  2252.     (call up the Find dialog and click "All")
  2253.     •    run the hAWK program "$EchoFullPathNames", and use
  2254.     Save As to save the resulting list of full path names
  2255.     • move the files
  2256.     • edit the disk or folder names in your list of full path names
  2257.     to reflect the new locations
  2258.     • create a new EnterAct project, hold down the <Shift> key,
  2259.     and select Add Files from List… - double-click on the file
  2260.     you created that contains the full path names.
  2261.  
  2262. (A fourth way to relocate files, activating the "Relocate files
  2263. automatically" option in the Options dialog, works only if all
  2264. your source and header files have unique names within the
  2265. context of their disks, and works only if you change the folder
  2266. where they reside - it doesn't work if you change disks. Use of
  2267. this option is NOT recommended, unless you're quite sure that
  2268. your files have unique names on their disks.)
  2269.  
  2270. EnterAct can handle the following changes to file and folders
  2271. without requiring you to make a new project:
  2272.     • renaming a folder
  2273.     • moving a folder around within one disk
  2274.     • moving a file to a different folder, provided the file
  2275.     name is unique on the disk, if you activate the "Relocate
  2276.     files automatically" option (see just above, not recommended
  2277.     for casual use)
  2278.  
  2279. As mentioned, EnterAct cannot track files if you move them
  2280. to a different disk, unless the two disks involved have the
  2281. same name. 
  2282.  
  2283. Tip: if you often restore your project files from another disk,
  2284. try using a smart copy utility such as CopyDoubler(tm) or equivalent:
  2285. this will preserve all folders involved, and EnterAct won't lose
  2286. track of any files due to two or more files having the same name.
  2287. Second-best for this case, make aliases for all the source folders
  2288. involved in your project, and place the aliases in your EnterAct
  2289. folder. Then you can build a new project quickly after restoring
  2290. your files, by dragging all the aliases at once onto your new
  2291. project window.
  2292.  
  2293. §    Creating a project
  2294. Select New Project from the EnterAct menu at any time. When you start
  2295. EnterAct by double–clicking on its icon, you’ll see the New Project
  2296. dialog if you cancel the Open Project dialog that appears first during
  2297. the startup. Since the the project will always be saved for you
  2298. automatically, there’s no such thing as an “Untitled” project: you’ll
  2299. have to give it a home on your disk before doing anything with it.
  2300.  
  2301.  
  2302.  
  2303.  
  2304.  
  2305.  
  2306.  
  2307.  
  2308.  
  2309.  
  2310.  
  2311.  
  2312.  
  2313. You can also use Save As to create a copy of an existing project. This
  2314. is a quicker approach if you want a basic set of files to be added to
  2315. a fresh project. To create a “starter” project, once you have a list
  2316. of files in mind:
  2317.     •    create a project that contains just the basic files, and give it
  2318.         a name that reflects its status as a “starter”
  2319.     •    bring the dictionary up to date, so this only has to be done once
  2320.         for the basic files
  2321.     •    set the font, size, and screen placement of the project window.
  2322.  
  2323. Thereafter, to use a “starter” project as the basis of a new project:
  2324.     •    open the starter project
  2325.     •    immediately use Save As, and give it an appropriate name
  2326.     •    proceed as with a new project, adding files and building the
  2327.         dictionary.
  2328.  
  2329. Candidates for inclusion in a “starter” project include toolbox headers
  2330. (omitting the ones you don’t need reduces memory needs) and the on-disk
  2331. manuals supplied with EnterAct. If you’re an object-oriented sort, then
  2332. many of the files in your class library of choice will qualify
  2333. as well.
  2334.  
  2335. §    Selecting your <system> folder
  2336. When you create a new project, a second dialog will appear asking you to
  2337. select the folder to designate as the <system> folder: this is the
  2338. folder where the "Add Mac Headers" command will search for your
  2339. Mac headers ("Quickdraw.h and friends), and it is also the folder used
  2340. to distinguish between All ".h" and All <.h> (or .c) in the Find dialog
  2341. when you are selecting files to search.
  2342.  
  2343. If you cancel the "Select <system> Folder" dialog when creating
  2344. a project, the folder that contains EnterAct itself will be used
  2345. by default. Rather than move EnterAct to your compiler's folder,
  2346. life is simpler if you make an alias for the folder that holds your
  2347. choice of toolbox headers, and put it in the folder where you will
  2348. keep your EnterAct project (personally, I keep them all in my
  2349. EnterAct Stuff folder). Then when you're asked to select a
  2350. <system> folder, select the alias you made. You can use a folder
  2351. that contains the toolbox headers, but things are easiest if the
  2352. folder you use does not contain two different versions of the
  2353. toolbox headers or some other important set of headers.
  2354.  
  2355. You can change the designated <system> folder for a project at
  2356. any time by using the "Select <system> Folder...." command under
  2357. the EnterAct menu.
  2358.  
  2359. §    Three panes—.c, .h, plain text
  2360. Any files you add to your project whose names end in .c, .C etc
  2361. (source files) will be placed in the left pane. Header files
  2362. (ending in .h, .H etc) will go in the middle pane, and any other
  2363. TEXT files that you add will end up in the right pane. PICT’s
  2364. will also be placed in the right pane.
  2365.  
  2366. Here's a complete list of file extensions that are recognised by
  2367. EnterAct:
  2368. ____
  2369. c C h H cp cpp c++ asm CP CPP C++ ASM hp hpp HP HPP Cpp
  2370. java Java jav Jav JAVA JAV
  2371. ____
  2372. Of these, the ones starting with h or H are added to the middle pane,
  2373. and all others are added to the leftmost pane.
  2374.  
  2375. If you have special file extensions after a period, eg “.Proto”, that
  2376. you would like to have treated as source or header files, see the
  2377. “Custom file extensions” section a few pages on.
  2378.  
  2379. The dictionary-builder does not look at files in the right pane, which
  2380. is reserved for documentation. However, it will extract definitions
  2381. and prototypes from all files in the left and middle panes. If you don't
  2382. want a file in the left or middle pane to be parsed by the dictionary
  2383. builder, hold down the <command> key and click on the file name
  2384. in the project window to place a dash '-' beside it.
  2385.  
  2386. In each pane, the files are sorted alphabetically by name. Since
  2387. EnterAct is not a compiler, there’s no need to set up code segments.
  2388.  
  2389. If you add more than one file with the same name, truncated full path
  2390. names will be shown to the right of the names so that you can tell
  2391. which one is which (usually).
  2392.  
  2393. §    Adding Java files
  2394. Nearly everything for Java files is the same as for C++ files.
  2395. For best results, find the source folder for the standard java libraries
  2396. somewhere (eg CW9) and drag it onto your project.
  2397.  
  2398. §    Add Files—the one-at-a-time way
  2399. The Add Files command will let you repeatedly add files (one at a time)
  2400. to your project, until you cancel the dialog. The appropriate pane for
  2401. each file will be chosen for you. The type of the file you add can be
  2402. TEXT or PICT.
  2403.  
  2404. §    Adding files from a list
  2405. The Add Files from List… command appears in place of
  2406. the Add Files command when you hold down the <Shift> or <Option> key.
  2407. A standard Open dialog will appear, in which you should select a text
  2408. file that contains a list of full path names of files to be added to your
  2409. project, one name per line. Within EnterAct, a list of full path names
  2410. can be generated by selecting the desired files in your project for
  2411. multi-file operations (hold down the <Option> key and click on the files
  2412. in your project window), and then running the hAWK program
  2413. $EchoFullPathNames. See the “Search” chapter for multi-file
  2414. selections, and Appendix 2 for hAWK.
  2415.  
  2416. Recommended, for VERY important projects take a minute to produce
  2417. a list of all files in your project:
  2418.     •    with the project open, call up Find and click the "All" button
  2419.         to place bullets beside all files (just make sure all disks for
  2420.         the files are mounted)
  2421.     • select "hAWK", pick the $EchoFullPathNames program from the
  2422.         top popup menu, and click "Run"
  2423.     •    Save the resulting document as "MyProj Files" or equivalent.
  2424.  
  2425. Later, if you need to recreate the project, you can do so quickly
  2426. with the Add Files from List… command. However, these days
  2427. it's simpler to create aliases for all the source folders involved
  2428. in your project, so recreating the project just involves dragging
  2429. the folder aliases onto a new project window.
  2430.  
  2431.  
  2432. §    Add All In Folder—the fast way
  2433. To add all files in a folder to your project:
  2434.     •    select Add All In Folder
  2435.     •    select a folder that contains files to be added
  2436.     •    click on the button with the folder's name at bottom
  2437.     •    do another folder, or Cancel
  2438.  
  2439. When you click the bottom button, all TEXT files in
  2440. the folder will be added to your project. Files in subfolders will not
  2441. be added. This command will also repeat until you click the Cancel
  2442. button. As with Add Files, there’s no need to select a project pane
  2443. beforehand.
  2444.  
  2445.  
  2446.  
  2447.  
  2448.  
  2449.  
  2450.  
  2451.  
  2452.  
  2453.  
  2454.  
  2455.  
  2456.  
  2457.  
  2458.  
  2459.  
  2460.  
  2461.  
  2462.  
  2463.  
  2464.  
  2465.  
  2466.  
  2467.  
  2468.  
  2469.  
  2470.  
  2471.  
  2472.  
  2473.  
  2474. (Clicking on the "CEDARL_Source" button would add all files in that
  2475. folder to the project, and also all files in subfolders if the <Shift>
  2476. key was down while picking the "Add Files" menu item.)
  2477.  
  2478. To add all files in all subfolders to your project as well, hold down
  2479. the <Shift> or <Option> key while picking  Add All In Subfolders (the key
  2480. command won’t work with the <Option> key, just the <Shift> key). Then
  2481. select a folder and click on the bottom button with its name.
  2482. .Note that <Command><period> will interrupt this all-inclusive
  2483. version of Add All In Folder, in case you start in the wrong place.
  2484. This <shift> version of Add All is the exact equivalent of dragging
  2485. a folder or folder alias onto your project window.
  2486.  
  2487. You can also select and add individual files with the Add All
  2488. command, but note this will have exactly the same effect
  2489. as selecting the folder that contains the file, adding all
  2490. files in the folder (and optionally subfolders).
  2491.  
  2492. §    Add Mac Headers
  2493. The Add Mac Headers command will search the folder that contains
  2494. EnterAct and all sub–folders for the file “Quickdraw.h”. Wherever it
  2495. is found, all files in that folder will be added. If not found, you will
  2496. see a message from EnterAct mentioning that “Quickdraw.h” wasn’t found
  2497. anywhere. You can add these headers yourself with the Add All
  2498. In Folder command.
  2499.  
  2500. If you hold down the <Shift> or <Option> key while selecting this
  2501. command, then in addition Add THINK Headers will also be done (see just
  2502. below).
  2503.  
  2504. If EnterAct complains that it can't find your toolbox files (or just as
  2505. bad, that if found more than one version), you can add the toolbox files
  2506. yourself--the easiest way is to make an alias for the toolbox headers
  2507. you want, and place it in your EnterAct folder. Then you can add the
  2508. headers by dragging the alias onto your project window.
  2509.  
  2510. §    Add THINK Headers
  2511. This command will add all files in the folder containing “THINK.h” to
  2512. your project. These include “asm.h”, “pascal.h”, “SANE.h” etc.
  2513. If you're using CodeWarrior or MPW, this command doesn't do much.
  2514.  
  2515.  
  2516. §    Add Standard C Headers
  2517. This command will add all files in the folder containing “stdio.h” to
  2518. your project.
  2519.  
  2520.  
  2521. §    The active pane
  2522. When you click in one of the three file lists it becomes the active
  2523. pane, as indicated by highlighting of the file name you click on, and
  2524. activation of the scroll bars for that pane. You can also switch
  2525. between panes by using the left and right arrow keys.
  2526.  
  2527. Some project-related commands such as Update Dictionary and Find In
  2528. Next File are independent of the active pane, while others act within
  2529. a particular pane. Here’s a list of commands and features which apply
  2530. to the active pane:
  2531.     •    the active pane is relevant only when the project window is in
  2532.         front, in which case one of the file names in the active pane will be
  2533.         highlighted, and the scroll bars will be active
  2534.     •    to scroll the currently-selected file in the active pane into view,
  2535.         press <Enter>
  2536.     •    as you drag about in the active pane the currently-selected file
  2537.         will change to keep up with your mouse, with full autoscrolling
  2538.     •    to move up and down the list of files in the active pane, use the
  2539.         up and down arrows. <Option><up arrow> selects the first file in the
  2540.         pane, and <Option><down arrow> selects the last file
  2541.     •    to change panes, click in the pane you want or use the <left arrow>
  2542.         and <right arrow> keys
  2543.     •    type part of a file name to advance to a particular file in the
  2544.         active pane, eg type "mou" to advance to either "Mouse.h" or
  2545.         "MAIN_Mouse.h" -- a match on the first part of the name is tried
  2546.         first, and if that fails then a match anywhere within the name counts
  2547.     •    Copy will copy the currently-selected file name in the active pane
  2548.     •    double-clicking on a file name opens the file, and the
  2549.         currently-selected file in the active pane can be opened with the Go
  2550.         to command
  2551.     •    the active pane is searchable with the Find and Find Again commands
  2552.         when the project window is in front, or just behind the Find dialog.
  2553.         Note that when the Find dialog is immediately in front of the project
  2554.         window the “Find” button will search the list of file names in the
  2555.         active pane, whereas the “Find In Next File” button will search through
  2556.         the contents of those files marked with bullets (•). Searching through
  2557.         the active pane for part of a file name or a file extension is handy
  2558.         when you have a great many files in a pane
  2559.     •    Remove File removes the currently-selected file in the active pane
  2560.         from the project, deleting both the file name and the associated
  2561.         dictionary entries.
  2562.  
  2563. §    Remove File
  2564. To remove one file from a project, bring the project window to the
  2565. front, select the file by clicking on it, and then select Remove File.
  2566. If you have built a dictionary for the project, the dictionary will
  2567. be automatically updated for you.
  2568.  
  2569.  
  2570. §    Remove •'d Files
  2571. The “•” refers to files in the project window that have been marked
  2572. for multi–file operations (a bullet • appears to the left of the file
  2573. name). Before issuing this command, first mark the files that you wish
  2574. to remove with bullets (<Option>drag over the files in the project
  2575. window). You can also mark all files of a particular type by using the
  2576. buttons in the Find dialog.
  2577.  
  2578. Any dictionary entries associated with the file will also be deleted.
  2579. See the next chapter for a description of your project dictionary.
  2580.  
  2581. By the way, this is the only command in EnterAct that will pay
  2582. attention to bullets beside PICT file names. All other commands which
  2583. deal will your list of bulleted files (such as Find In Next File, or
  2584. passing the list as input to a hAWK program) will quietly ignore the
  2585. PICT files, since all other multi-file commands deal only with text
  2586. files.
  2587.  
  2588.  
  2589. §    Custom file extensions
  2590. The File Extensions command under the EnterAct menu allows you
  2591. to specify additional file extensions beyond the standard .c, .C, .h,
  2592. .H etc. Type in your own extensions (up to 48 extensions, each up to
  2593. 5 characters), and pick which pane the file should be added to. For
  2594. example to have “.Proto” files added to the middle pane, type in
  2595. “Proto” (don't type the period) in one of the extension fields and
  2596. click the corresponding “Mid pane” button. Extensions are
  2597. case-sensitive, so “PROTO” is not the same as “Proto”. If you have
  2598. multiple versions of the same extension, you should enter them
  2599. separately.
  2600.  
  2601. If a project is open when you pick File Extensions the extensions you
  2602. enter will apply to that project only, as indicated by the “This
  2603. project” button. If no project is open at the time, the extensions will
  2604. be used for any new project you create (the bottom-left button will
  2605. read “New projects” in this case).
  2606.  
  2607. Please note any file that is added to the left or middle panes will
  2608. be parsed, and terms contained will be built into your dictionary, as
  2609. explained in the next chapter on dictionaries. This means the files
  2610. must be in C/C++/Java (or at least “C--”), otherwise the dictionary builder
  2611. will complain. To get around this for an individual file, <command>click
  2612. on the file name in the project window to place a dash '-' beside it.
  2613.  
  2614. One use for this that you might like to explore later is creating your
  2615. own “.Note” files. The “.Note” extension will remind you of their
  2616. contents, namely hyperlinked notes on any subject that can be called
  2617. up with a click and press of the <Enter> key. This is described at
  2618. length in the “Lookup” chapter, which you’ll get to eventually if you
  2619. just keep reading along.
  2620.  
  2621. Here’s what the File Extensions dialog looks like:
  2622.  
  2623.  
  2624.  
  2625.  
  2626.  
  2627.  
  2628.  
  2629.  
  2630.  
  2631.  
  2632.  
  2633.  
  2634.  
  2635.  
  2636.  
  2637.  
  2638.  
  2639.  
  2640.  
  2641.  
  2642. ("This project" reads "New projects" if you don't have a project open)
  2643.  
  2644. §    Distinguishing ".h" from <.h>
  2645. The All ".h" and All <.h> buttons in the Find dialog let you set up a
  2646. multi–file search for just one kind of header (ie system or your own),
  2647. and since bullets • are shown beside selected files selecting one or
  2648. the other kind will give you an on–screen way of telling which are
  2649. which. Similarly, the All ".c" and All <.c> buttons allow you to select
  2650. source files in either your project folder or your system folder
  2651. for multi-file operations such as searching. The "system" folder
  2652. is the one that contains EnterAct.
  2653.  
  2654. Note for this to work properly you must select the appropriate
  2655. <System> folder either when making the project or at any time
  2656. thereafter using the "Select <system> folder..." command.
  2657.  
  2658. Technically, the Find buttons mentioned above bullet files in the left
  2659. or middle pane based soley on their disk location. In particular, any files
  2660. with custom file extensions such as “PROTO” or “Notes” will end up with
  2661. bullets if they they fall in the category selected (<.h> and <.c> for
  2662. the <system> folder, ".h" and ".c" for elsewhere).
  2663.  
  2664. §    Copy and search in the project window
  2665. When you have a file name selected in the project window, you can Copy
  2666. it and then Paste it into a text window. This helps sometimes with
  2667. documentation. 
  2668.  
  2669. With the project window in front, you can type as in a Finder window to
  2670. advance the selection in the current project pane to the first file name
  2671. that begins with the characters you typed. You can also type any unique
  2672. part of a file name to select it, for example if you have the source pane
  2673. selected and "NPXWE_DialogHandler.cp" is the only file name in the pane
  2674. that contains "Dial", then typing "dial" will select that file. Neat!
  2675.  
  2676. And, if you have an enormous project, the Find dialog will let you
  2677. search for part or all of a file name in a particular pane. Select the
  2678. pane in the project window that you wish to search, call up the Find
  2679. dialog, and then continue as though you were searching for something
  2680. in a text document.
  2681.  
  2682.  
  2683. §    Project memory needs
  2684. EnterAct will be keeping your entire project dictionary in memory, for
  2685. rapid access, and this does place a practical limit on the size of a
  2686. project. Roughly, the memory needed will amount to 500K for basic
  2687. operations plus 16% of the size of all source (left-pane) files plus
  2688. 120% of the size of all header (middle-pane) files, with “size” meaning
  2689. the size of a file’s data fork in bytes, rather than the disk space
  2690. used. Note that toolbox and other header files can take a large memory
  2691. bite, so if memory becomes tight your greatest savings can be realised
  2692. by removing header files that you don’t really need built into your
  2693. dictionary.
  2694.  
  2695. As a rule of thumb, give a small project about 2 Meg to work with,
  2696. and allow about 7 Meg for a larger one (say 1 Meg of source code with most
  2697. toolbox headers).
  2698.  
  2699. For more details, especially on toolbox headers and their memory needs,
  2700. please see the document “EnterAct memory needs”.
  2701.  
  2702.  
  2703. §    Multi-file selection
  2704. The general notion is to select one or more of the project files listed
  2705. in your project window, and then issue a command that acts on all
  2706. selected files. The classic use is for multi-file searching.
  2707.  
  2708. To create a multi-file selection for your current project:
  2709.     •    (Coarse tuning) in the Find dialog, click on the various buttons
  2710.         that select all files of a particular type
  2711.     •    (Fine tuning) hold down the <Option> key and click on or drag over
  2712.         file names in the project window. This acts as a “toggle”, selecting
  2713.         files if they were not selected and vice versa. The cursor will change
  2714.         to an “eye” when it’s over the project window with the <Option> key
  2715.         down.
  2716.  
  2717. Each file included in your multi-file selection will have a bullet (•)
  2718. to the left of its name in the project window.
  2719.  
  2720. Your multi-file selection can be used in the following ways:
  2721.     •    to carry out a multi-file search; enter the text to be found in the
  2722.         Find dialog, and click the “Find In Next File” button there, or use
  2723.         the equivalent command under the Search menu. For more on this, see
  2724.         the “Search” chapter.
  2725.     •    to remove files from your project; use the Remove •'d Files command
  2726.         described earlier in this chapter
  2727.     •    as input to a hAWK program; for example, to generate a list of full
  2728.         path names for all text files in your multi-file selection:
  2729.         •    select the hAWK command under the EnterAct menu
  2730.         •    use the “Program:" popup menu to select “$EchoFullPathNames”
  2731.         •    click the “Run” button, and wait a bit... the list of full
  2732.             path names will be shown to you in a fresh window.
  2733.     •    as input for one of the “Index" commands, as described in
  2734.         the “‘Index’ commands” chapter.
  2735.  
  2736. For more on hAWK see the “hAWK User’s Manual”.
  2737.  
  2738.  
  2739.  
  2740.  
  2741.  
  2742.  
  2743.  
  2744.  
  2745.  
  2746.  
  2747.  
  2748.  
  2749.  
  2750.  
  2751.  
  2752.  
  2753.  
  2754.  
  2755.  
  2756.  
  2757.  
  2758.  
  2759.  
  2760.  
  2761.  
  2762.  
  2763.  
  2764.  
  2765. (Coarse-tune your multi-file selection with buttons in the Find dialog,
  2766. fine-tune it by holding down the <Option> key and dragging over files
  2767. in the project window)
  2768.  
  2769.  
  2770. §    Project context restoration
  2771. When you close a project, or quit with a project open, the project will
  2772. keep a list of all project documents that are open at the time. That’s
  2773. your “context”. The next time you open the project, all of those
  2774. project documents will also be reopened, and placed and scrolled much
  2775. as you left them, and the Browser window will also be brought back if
  2776. you left it open. This is all automatic, so in the rare event that you
  2777. don’t want your context restored, do a Close All before closing the
  2778. project or quitting.
  2779.  
  2780. Some details: your windows will be put back exactly where you left
  2781. them; file errors are suppressed during context restoration, so if a
  2782. document seems to be missing try double–clicking on it in the project
  2783. window; text documents will be restored with your insertion point or
  2784. selection range scrolled into view, to avoid confusion; however, if
  2785. a document is already open, only its window order will be restored;
  2786. and if a document has been edited (anywhere) while the project was
  2787. closed, it won’t be scrolled. Lookup windows and  documents that
  2788. haven’t been added to your project (including “Untitled” windows) are
  2789. not restored. However, AutoLook will be restored.
  2790.  
  2791. If you’re about to switch from one project to another, and want the
  2792. project being closed to remember and restore the open documents, close
  2793. the project before closing any of the documents that you want
  2794. remembered—then open the other project.
  2795.  
  2796. §    Switching to other projects
  2797. <Option> or <Command> click in the title bar of a project window to
  2798. view a popup list of other projects that you have had open.
  2799. When you pick one  from the list, your current project will close and
  2800. the one you picked will open. If you use the <Option> key, you will be
  2801. asked to save any documents that need saving, and all text windows
  2802. will be closed. If you use the <Command> key, all your text windows
  2803. will be left open. Using the <Option> key to close all windows
  2804. between switches is the better approach if all of the files you
  2805. are dealing with are in your projects, since it keeps your screen
  2806. from becoming buried under a sea of windows.
  2807.  
  2808. §    Tips
  2809. When you double–click on a file name in the project window to open a
  2810. file, the project window will at the same time move to the back behind
  2811. all other windows. If the project window becomes hidden, you can bring
  2812. it to the front again by selecting it from the Windows menu or using
  2813. the menu key equivalent <Command><zero> which is always for the project
  2814. window. Since the project window goes all the way front or back with
  2815. a key–stroke or double–click, you can if you wish make the project
  2816. window relatively large and treat it as a sort of backdrop mini–Finder
  2817.  
  2818. If you begin the names of your own header files with a common character
  2819. or group of characters, they will end up grouped together in the middle
  2820. pane of your project window, and similarly for the other panes.
  2821. Remember you don't have to type the prefix to select a file
  2822. in the active pane, you just need to type some distinctive part of
  2823. the name.
  2824.  
  2825. If you're short on memory:
  2826. To save on memory needed for dictionaries, create one or more “generic”
  2827. projects which include header files that are often needed—and exclude
  2828. headers than aren’t often needed. Select Update Dictionary before
  2829. putting your generic project away. When you want to create a new
  2830. project, open the appropriate generic one and use Save As to give it
  2831. a new name. This way you won’t have to weed out unneeded headers to
  2832. minimize memory needs, and your dictionary will already be up to date
  2833. for the basic headers.
  2834.  
  2835. -    -    -    -    -    -    -    -    -    -    -    -
  2836. Dictionaries
  2837. -    -    -    -    -    -    -    -    -    -    -    -
  2838. §    Introduction
  2839. Once built, a project’s dictionary will contain entries for virtually
  2840. every C/C++/Java term in every source (left pane) or header (middle pane)
  2841. project file that is not restricted in scope to the body of a function.
  2842. For functions and methods the dictionary entry will
  2843. be the prototype or equivalent, and for all other terms the entry will
  2844. consist of the entire statement in your source code in which the term
  2845. was mentioned or defined. Regular use of Update Dictionary will keep
  2846. your dictionary current as you develop your source code.
  2847.  
  2848. As explained in the next chapter, the main point of having a dictionary
  2849. is to give you instant displays of those definitions and prototypes.
  2850. The AutoLook window shows them automatically as you edit, and more
  2851. detailed and permanent displays can be generated by double-clicking
  2852. on a name and pressing the <Enter> key. You can also jump to the
  2853. definition of any dictionary entry, as explained in the “Seeing where
  2854. a term is defined” chapter. The project dictionary forms the basis for
  2855. the display in the Browser window. And there’s a hAWK built-in function
  2856. that lets you determine the type of a C term within the context of your
  2857. current project (see the hAWK program “$Whazzat”, which
  2858. translates C declarations into English).
  2859.  
  2860. The AutoLook window can also display definitions for local variables.
  2861. For this to work, in addition to having a dictionary you should be
  2862. working inside a function in a source file.
  2863.  
  2864.  
  2865. §    What’s in a dictionary
  2866. After you’ve built your dictionary with the Update Dictionary command
  2867. (see the next section), it will contain entries for everything of
  2868. interest in your current project’s source (left pane) and header
  2869. (middle pane) files that you would want to use in more than one 
  2870. function. Specifically there will be an entry for every:
  2871.     •    function—all types including static, in–line, method
  2872.     •    struct, union, enum, class
  2873.     •    enum constant
  2874.     •    #define—constant and macro
  2875.     •    typedef
  2876.     •    variable—all types including static, low–memory
  2877.  
  2878. —provided only that the term is defined or mentioned outside of a
  2879. function.
  2880.  
  2881. Note that members of classes, structs and unions are included, as
  2882. are prototypes or definitions of methods within class definitions.
  2883. Local variables are not included in your dictionary, but the AutoLook
  2884. window can look at your function to find the variable's defining
  2885. type name (which should be a keyword or something in your
  2886. dictionary).
  2887.  
  2888. Dictionary entries for functions and methods will contain the prototype
  2889. or equivalent. For all other kinds of terms, the dictionary entry will
  2890. consist of the complete C statement in which the term occurs in your
  2891. source code.
  2892.  
  2893. All variants of a particular term will be included as separate entries
  2894. in the dictionary. For example, if your source code contains the
  2895. definition of a function and also a prototype for the function, then
  2896. two entries for the function will be made in the dictionary. 
  2897.  
  2898. When EnterAct runs into conditional inclusion such as
  2899.  “#ifdef SomeThing ...  #else ...#endif”, it picks up definitions
  2900.  in the first part and ignores the "else" or "elif" sections. The
  2901.  parser also ignores anything inside the standard
  2902.  “#if 0 ... #endif” construction.
  2903.  
  2904. §    Building your dictionary
  2905. To exclude a file from being built into your dictionary, hold down
  2906. the <Command> key and click on the file's name in the project
  2907. window. The cursor will change to an 'X' while you do this, and
  2908. a dash '-' will appear to the left of the file name to show that it
  2909. is excluded.
  2910.  
  2911. If you are adding files from a list (via <Shift>Add Files...), you can
  2912. exclude a file from being built into the dictionary by placing an
  2913. exclamation mark at the beginning of its path name, eg to exclude
  2914. the file
  2915. ____
  2916. HardDisk:Folder:src:George.cp
  2917. ____
  2918. add a '!' so it reads
  2919. ____
  2920. !HardDisk:Folder:src:George.cp
  2921. ____
  2922.  
  2923. After you’ve added all your files to your project, select Update
  2924. Dictionary from the EnterAct menu. If the dictionary–builder stumbles
  2925. over a statement that’s too mangled to parse, you’ll see a message
  2926. explaining in general what the problem is. You’ll also be shown the
  2927. file in question, with the cursor placed at the position where the
  2928. error was detected. Generally, most problems reported will be
  2929. well–localised and fairly easy to fix—typical problems are lack of
  2930. balance for critical delimiters, and missing or very badly spelled
  2931. keywords. If you don’t see what the problem is, consult the “Dictionary
  2932. build problems” section of the “If there’s a problem” chapter.
  2933.  
  2934. EnterAct’s dictionary–builder will properly interpret a great many
  2935. first–draft errors, including missing semi–colons, lack of balance in
  2936. some delimiters (these vary according to context), slightly misspelled
  2937. keywords, and some others. Your source code should mostly make
  2938. sense, but it doesn't have to be perfect.
  2939.  
  2940. In a contrary sort of way, using EnterAct will almost certainly
  2941. reduce your first–draft errors. This is simply because you now have
  2942. instant access to all spellings and types of struct members, all
  2943. function and method calls, etc, so a major source of errors
  2944. is now gone.
  2945.  
  2946. §    Keeping it up to date
  2947. EnterAct does not update your dictionary automatically. Generally, you
  2948. should select Update Dictionary whenever you change or add something
  2949. that you’d like to have in the dictionary. Changes that take place
  2950. entirely within the body of a function will not affect what’s in your
  2951. dictionary. Any changes outside of a function body, including adding
  2952. a new function, adding or changing an enum constant or struct or class
  2953. member etc will be changes that you’d normally like to have reflected
  2954. in your dictionary.
  2955.  
  2956. Update Dictionary checks each file's modification time against the
  2957. time it was last updated by Enteract, so there is no need to "make"
  2958. an EnterAct project as a separate step.
  2959.  
  2960. Update For Front File Only will rebuild only that part of your
  2961. dictionary that is determined by the front text window. Unlike the
  2962. other two update commands, this is a “manual override”, and rebuilds
  2963. the dictionary for the front file whether or not it needs rebuilding.
  2964. Normally you won’t need to use this command, because a full update with
  2965. Update Dictionary for all changed files is almost always very quick.
  2966.  
  2967. There are two special cases in which you’ll probably want to rebuild
  2968. your entire dictionary:
  2969.     •     enabling the “Detect nested comment start” option (see “Option”
  2970.          chapter), after having done a dictionary update with this option
  2971.          disabled
  2972.     •    adding one or more new “macro’s to skip” (see the section on
  2973.         “All-or-nothing macro’s” in the “Source code restrictions chapter)
  2974.  
  2975. To completely rebuild your dictionary, hold down all three of the
  2976. <Shift>, <Option>, and <Command> keys while using the mouse to select
  2977. Update Dictionary (note the key equivalent doesn’t work with this
  2978. variation).
  2979.  
  2980. A small point, but worth noting: if you make a significant change to
  2981. a header file that’s #included in a great many source files, don’t be
  2982. reluctant to bring your dictionary up to date. EnterAct’s dictionary
  2983. builder only needs to scan changed files once, no matter how they are
  2984. #included. The dictionary update will take just a few seconds at most
  2985. (the tedious part, saving the new dictionary to disk, is done
  2986. transparently while you continue to work). For example, on a
  2987. relatively slow machine with a 68040 running at 25 Mhz, a typical
  2988. incremental update will take 5-10 seconds.
  2989.  
  2990.  
  2991. §    How long will it take?
  2992. Typically an update zips along at two to three files per second on a slow
  2993. 68040 machine once it gets going. There is a bit of overhead at the end
  2994. of an update while the browser is rebuilt, roughly three seconds.
  2995. Project dictionary saving is done transparently in the
  2996. background unless you close the project or Quit or issue some other
  2997. command that requires a fully-saved project. You can go back to editing,
  2998. looking things up, searching etc right after the last file is parsed.
  2999.  
  3000. On a Quadra 840 or faster, update speed is simply astonishing.
  3001.  
  3002. As mentioned above, all changed files including ".h" files are scanned
  3003. only once during an update.
  3004.  
  3005. Your regular dictionary update will probably involve no more than
  3006. four files, and for this your total time "lost" will typically be under
  3007. under six seconds. On a Quadra 840, blink and you miss it.
  3008.  
  3009. If you need to interrupt the dictionary update, press
  3010. <Command><period>. This also interrupts multi–file searches, and
  3011. printing, and hAWK programs, by the way. You can finish the job off
  3012. properly later by reselecting your original dictionary update command.
  3013.  
  3014.  
  3015. §    Show Dictionary
  3016. (This command is not especially useful, since in practice most
  3017. dictionaries are very big, and you'll run out of memory.)
  3018.  
  3019. This command produces a “raw” dump of all the text in your dictionary,
  3020. consisting of all the definitions or declarations that the
  3021. dictionary–builder extracted from your code. At the top will be a
  3022. comment listing the number of definitions of each type. The entries
  3023. in the dictionary dump will be grouped together by file after a comment
  3024. giving the file name, and within each file will appear in the same
  3025. order as they occurred in the original file. You can use Save As if
  3026. you wish to save your raw dictionary.
  3027.  
  3028.  
  3029.  
  3030.  
  3031.  
  3032.  
  3033.  
  3034.  
  3035.  
  3036.  
  3037.  
  3038.  
  3039.  
  3040.  
  3041.  
  3042.  
  3043.  
  3044.  
  3045.  
  3046.  
  3047.  
  3048.  
  3049.  
  3050.  
  3051.  
  3052.  
  3053.  
  3054. -    -    -    -    -    -    -    -    -    -    -    -
  3055. Lookup
  3056. -    -    -    -    -    -    -    -    -    -    -    -
  3057. You can expect that better than 90% of your routine information needs
  3058. will be satisfied by the AutoLook window. For remaining needs, regular
  3059. lookup (press <Enter>) pulls up definitions of terms to separate
  3060. windows, and also works when your spelling is off but “distinctively
  3061. close”. And reverse lookup (<Shift><Enter>) shows definitions of
  3062. structs, unions, and typedefs that contain a particular member, again
  3063. in a separate window.
  3064.  
  3065. Please note that definitions of local variables appear only in the
  3066. AutoLook window, and if you want them in a separate window
  3067. you'll have to do the Copy-New-Paste thing.
  3068.  
  3069. Lookup and many other features (such as jumping to a definition) are
  3070. fully functional with first-draft code. All lookup windows, including
  3071. AutoLook, are fully editable, but can't be saved.
  3072.  
  3073. EnterAct's lookup features can be used to help out less "language
  3074. aware" editors. If you feel more comfortable working that way,
  3075. see the last section in this chapter (but read just below about
  3076. <Enter> for lookup, <Shift><Enter> for member lookup, and the
  3077. all-important AutoLook window first, please).
  3078.  
  3079. §    AutoLook
  3080. The AutoLook command calls up an automatic lookup window which
  3081. updates by itself to show dictionary entries as you type, edit, or
  3082. click around with the mouse. It will instantly retrieve and display a
  3083. definition for the words that lie just before your insertion point, or
  3084. within your current selection (which can be part of a larger
  3085. word). And it’s just as editable as a regular text window (Cut Copy
  3086. Replace etc), though you can’t save changes to it.
  3087.  
  3088. AutoLook is context-aware: it can determine if a name is a local
  3089. variable, and when dealing with members or methods it tries its
  3090. best to look in the appropriate inheritance chain. If you're in a
  3091. plain document rather than a source file, AutoLook still works,
  3092. but with less accuracy.
  3093.  
  3094. AutoLook can be used to look up a simple name, such as
  3095. "noErr": just click after the name and its definition will appear
  3096. instantly in the AutoLook window (for this one, you'd need to
  3097. add Mac Headers, or at least Types.h, to your project).
  3098.  
  3099. And AutoLook can be used to resolve a complicated "reference
  3100. chain". Taking a C example such as
  3101. ____
  3102.     mySFRPtr->sfFile.parID
  3103. ____
  3104. if you clicked after "parID" you would see in AutoLook that it
  3105. is a long member in an FSSpec; and if you clicked after "sfFile",
  3106. AutoLook would show that it is the FSSpec member in a
  3107. StandardFileReply struct. And if you clicked after "mySFRPtr"
  3108. in the function where I took this example, you would see that
  3109. it is a local variable of type "StandardFileReply    *", together
  3110. with the definition of a StandardFileReply. Actually, AutoLook
  3111. is much easier to use than to describe--try it! Just click after
  3112. any name of interest, anywhere.
  3113.  
  3114. Summary:
  3115.     • AutoLook shows definitions instantly for terms to the left
  3116. of your insertion point, or within your selection
  3117.     • If you're working inside a function in a source file, then the
  3118. AutoLook window will also display definitions for local variables.
  3119.     • If you're working within a method, lookup shown for members
  3120. and methods will be more accurate than if you're in a plain
  3121. document
  3122.     • Your spelling must be exact for most terms - if you don't see what
  3123. you expected, press the <Enter> key to look up a top-level term,
  3124. or <Shift><Enter> to look up a struct or class member (see below)
  3125.     • AutoLook shows supporting definitions for a name when
  3126. appropriate (eg if a name is a variable of type FSSpec, you'll
  3127. also be shown the definition of an FSSpec).
  3128.  
  3129. For another example, if there are entries in your current dictionary for
  3130. “Window”, “WindowData”, and “WindowDataPtr”, then all three entries
  3131. will appear in succesion in the AutoLook window as you type
  3132. “WindowDataPtr”. Selecting “Ptr” will call up the definition of “Ptr”,
  3133. whereas selecting (or clicking after) “contained within the
  3134. WindowDataPtr” will call up the definition of “WindowDataPtr”.
  3135. In both of these latter cases, the full definition of the "WindowData"
  3136. struct will appear in the AutoLook window.
  3137.  
  3138. If the definition of the word involves obvious typedefs,
  3139. #defines, or structs or unions, definitions for them will be appended to the
  3140. AutoLook display—for example, if you double-click on a global variable
  3141. gEvtDetails you won’t see just
  3142.     "EventDetails        gEvtDetails ;"
  3143. you’ll also see what an EventDetails thing is defined to be.
  3144.  
  3145.  
  3146.  
  3147.  
  3148.  
  3149.  
  3150.  
  3151.  
  3152.  
  3153.  
  3154.  
  3155.  
  3156.  
  3157.  
  3158.  
  3159.  
  3160.  
  3161.  
  3162.  
  3163.  
  3164. (as of v3.5, we skip the "middlemen", for example the typedef for
  3165. "EventDetails" is not shown in AutoLook, since it adds little
  3166. to comprehension)
  3167.  
  3168. As mentioned, the AutoLook window produces fast accurate lookup for
  3169. data members, when you're working in a method. Click after or
  3170. double-click on the data member's name, as usual, and the
  3171. declaration for the data member will appear in the AutoLook
  3172. window, followed by any supporting definitions -- eg "Thing
  3173. *dataMember;" would be followed by the definition of "Thing".
  3174.  
  3175.  
  3176.  
  3177.  
  3178.  
  3179.  
  3180.  
  3181.  
  3182.  
  3183.  
  3184.  
  3185.  
  3186.  
  3187.  
  3188.  
  3189.  
  3190.  
  3191.  
  3192.  
  3193.  
  3194.  
  3195.  
  3196.  
  3197.  
  3198.  
  3199.  
  3200.  
  3201.  
  3202. The AutoLook window will tell you which class
  3203. definition the declaration was found in, either the class that owns
  3204. the method you're working in, or any of the classes it inherits
  3205. from. This "data member" lookup for AutoLook is case-sensitive,
  3206. and the beginning of the name you're looking up must match the
  3207. beginning of the data member's name exactly, to speed things up
  3208. and cut down on spurious matches. If you're not working in a method
  3209. or your spelling is slightly off, AutoLook will still often take a stab
  3210. at showing you a definition, but it may just be guessing.
  3211.  
  3212. EnterAct's parser doesn't resolve overloaded method names, so you
  3213. may see more definitions than you want when you look up such a
  3214. name.
  3215.  
  3216. §    Regular lookup (press <Enter>)
  3217. The AutoLook window changes as you work, doesn't always show all
  3218. variants, and works only with correct spelling. To produce a more
  3219. permanent display of a definition, or a display listing all variant
  3220. definitions of a name, or to pull up a definition for a name when
  3221. you’ve forgotten the correct spelling, press the <Enter> key. You can
  3222. either double-click on the name or type it in or click just to the
  3223. right of it, then press <Enter>.  As a special case, note that local
  3224. variables are not in your dictonary and so definitions for them will
  3225. show only in the AutoLook window. This may change in a future version.
  3226. Hey, the top of the function isn't that far away. To toggle between
  3227. your working position and the top of a function, use the "Go Back"
  3228. command, or mark both locations using the Locations menu.
  3229. To produce a more permanent display of a local definition,
  3230. you'll have to manually copy it to another window.
  3231.  
  3232. Lookup windows also provide a context for jumping to one of
  3233. several definitions for a term, as described in chapter 11,
  3234. "Seeing where a term is defined." In brief, to jump to a specific
  3235. definition for a term:
  3236.     • press <Enter> to look the term up to a separate lookup window
  3237.     • pick the one you want; either <Option>click in the lookup
  3238.         window's title bar, or keep pressing <Enter>
  3239.     • <Option>double-click on the term you want (for a two-part name
  3240.         such as "Class::method", do the double-click on one name and then
  3241.         drag to the other name before releasing the mouse).
  3242.  
  3243. Back to pushing the <Enter> key: definitions that match or come
  3244. closest to the term you’re looking up will be displayed in a new
  3245. “lookup” window. It looks like a regular text window, but the title
  3246. of the window will be the term you’re looking up, preceded by
  3247. two bullets (••). Text in the window can be edited (Cut Copy
  3248. Replace etc), but changes are temporary.
  3249.  
  3250. In the display box along the bottom of the window you will see the name
  3251. of the file from which the definition was taken, followed by a number
  3252. such as “1/4” indicating that the definition is the first of four
  3253. available in the window. This number can range from “1/1” to “1/60”.
  3254. In all lookup windows, to view other definitions:
  3255.  
  3256.     •    hold down the <Option> key (or the <Command> key)
  3257.     •    click-and-drag in the lookup window’s title bar
  3258.     •    select from the resulting popup menu describing the definitions.
  3259.  
  3260. Or, press the <Enter> key to view the next available definition,
  3261. <Option><Enter> to view the previous one.
  3262.  
  3263.  
  3264.  
  3265.  
  3266.  
  3267.  
  3268.  
  3269.  
  3270.  
  3271.  
  3272.  
  3273.  
  3274.  
  3275.  
  3276.  
  3277.  
  3278.  
  3279. (Double-clicking on “KeyDetails” and pressing the <Enter> key produced
  3280. the “••KeyDetails” lookup window. The cursor is caught in the act of
  3281. an <Option>click in the title bar of the lookup window.)
  3282.  
  3283. When your spelling is exact, the lookup window will contain all variant
  3284. definitions of the term. For example, there will often be a defining
  3285. instance and prototype for a function, and quite often a struct and
  3286. a typedef with the same name will exist.
  3287.  
  3288. Unlike AutoLook, regular lookup works even if your spelling is off.
  3289. There are no arcane rules to memorize concerning what to type if you
  3290. can’t remember the exact spelling of a term: just type your best guess.
  3291. Do use the correct case though, because regular lookup is
  3292. case-sensitive, the same as C itself. OK, regular lookup will compensate
  3293. instantly for a single case error, but otherwise it will start looking
  3294. for best matches through your whole dictionary, and this takes a
  3295. moment.
  3296.  
  3297. If your spelling was off, the lookup window will hold definitions for
  3298. terms that best match what you typed, in order according to how well
  3299. they match. In this case, you control how many matches are available
  3300. in the lookup window (see “Number of entries per lookup” later in this
  3301. chapter, it's a field in the Options dialog).
  3302.  
  3303. When your spelling is incorrect, EnterAct first checks for common
  3304. errors such as full spelling when an abbreviation is needed, use of
  3305. a common synonym, permutations, and single case errors. Up to this
  3306. point, regular lookup is instant. If no match is yet found, EnterAct
  3307. then checks all entries in your dictionary and locates the ones that
  3308. best match what you typed, based on runs of matching characters. This
  3309. phase may take several seconds, but is still much faster and easier
  3310. than searching through files yourself. Very much faster.
  3311.  
  3312. As each definition appears in a lookup window, a selection is made for
  3313. you. For functions, the function name and parameter list are selected,
  3314. and for all other terms the name of the term itself is selected.
  3315.  
  3316. Here’s a general example illustrating typical use of regular lookup:
  3317.     •    you type the name of a function in one of your working windows, but
  3318.         the AutoLook window doesn’t change: this means your spelling was off
  3319.     •    press the <Enter> key, and a lookup window appears, holding several
  3320.         definitions that come closest to your spelling
  3321.     •    the first one shown isn’t the one you wanted: press <Enter>
  3322.         repeatedly to advance through the definitions. Normally the one you
  3323.         want will be among the first three. Or, hold down the <Option>
  3324.         or <Command> key and click-and-drag in the title bar to pick
  3325.         from a popup menu of alternates
  3326.     •    viewing the function you want, use Paste Selection Behind to copy
  3327.         the function name and parameters which have been selected for you,
  3328.         return to your working window, and paste the function name (now
  3329.         correctly spelled) and parameter list over your guess—all in one step.
  3330.  
  3331. §    <Enter> for lookup, advancing, scrolling
  3332. Pressing the <Enter> key in a normal text window means “look this up”,
  3333. but in a lookup window it can also mean “advance to the next
  3334. definition”. The different behavior corresponds to your intent. Here
  3335. are the rules for <Enter> in a lookup window:
  3336.     •    to look up a name shown in a lookup window definition, double-click
  3337.         on it or click after it or type it in and press <Enter>. This is the
  3338.         same as in a regular text window.
  3339.     •    to cycle to the next definition; if you haven’t altered the default
  3340.         selection made for you in the lookup window, press <Enter>. If you have
  3341.         altered the selection, use Select All before pressing <Enter>. If your
  3342.         selection is so large that it couldn’t represent a word to be looked
  3343.         up, or if it agrees with the name of the definition already being shown
  3344.         in the lookup window, EnterAct will cycle you to the next definition.
  3345.  
  3346. The same rules apply to <Option><Enter>, which takes you back to the
  3347. preceding definition in a lookup window, but also does “sounds like”
  3348. lookup as described as few sections ahead.
  3349.  
  3350. By the way, using the <Enter> key to just scroll the top-left of your
  3351. selection into view or to toggle between showing the top and bottom
  3352. portion of a large selection still works, the same as in ordinary
  3353. editors. Once again, it comes down to your intent: try the <Enter> key
  3354. out to do lookup, advancing through definitions, and scrolling your
  3355. selection and you should quickly find that you can treat it as a “Do
  3356. What I Mean” button. On the rare occasion when it doesn't advance you
  3357. to the next definition in a lookup window, whack it twice quickly.
  3358. That'll teach it.
  3359.  
  3360. §    Looking up the clip (press <Command><Enter>)
  3361. To look up the last word on the clipboard, hold down the <Command> key
  3362. while pressing <Enter>. EnterAct’s private clipboard is updated when
  3363. you switch in and out. So to look up a term encountered while using
  3364. some other editor:
  3365.     •    Copy just the term
  3366.     •    switch to EnterAct (an appropriate project with built dictionary
  3367.         should be open)
  3368.     •    hit <Command><Enter>
  3369.  
  3370. A lookup window will appear after you press the <Enter> key, showing
  3371. the dictionary entry that best matches what you typed, or those that
  3372. come closest if your spelling erred, just as if you typed the word in
  3373. a text window and pressed <Enter>.
  3374.     
  3375.     OR just leave your AutoLook window in front -- when you return
  3376.         to EnterAct, the AutoLook window will automatically display
  3377.         whatever info it can for the last word on the clipboard. This
  3378.         lets you use EnterAct as a high-speed lookup helper when
  3379.         you're working mainly with some other editor. Just arrange
  3380.         your windows so that you can see the AutoLook window when
  3381.         you're in the other editor, then having a definition in view is
  3382.         as easy as Copy, click on the AutoLook window, click on your
  3383.         other editor's window. 
  3384.  
  3385.  
  3386. §    Reverse lookup (press <Shift><Enter>)
  3387. To retrieve all struct, typedef, and union definitions that contain
  3388. a word or phrase, select the word or phrase, or click after just a
  3389. single word, and press <Shift><Enter>. Reverse lookup is not
  3390. case-sensitive, but otherwise your spelling must be exact. It’s very
  3391. fast, though not instant.
  3392.  
  3393. Results are shown in a lookup window, and you can view the different
  3394. definitions either by pressing <Enter> to advance to the next
  3395. definition, <Option><Enter> to view the previous one, or by
  3396. <Option>clicking in the lookup window’s title bar.
  3397.  
  3398. Here’s the lookup window that results from typing "ioFDirIndex" and
  3399. pressing <Shift><Enter>, with the dictionary containing most toolbox
  3400. headers:
  3401.  
  3402.  
  3403.  
  3404.  
  3405.  
  3406.  
  3407.  
  3408.  
  3409.  
  3410.  
  3411.  
  3412.  
  3413.  
  3414.  
  3415. (<Option>click in the title bar for the popup listing definitions in
  3416. any lookup window. “iofdirindex” would work just
  3417. as well as “ioFDirIndex”, and “ioFDir” would have produced similar
  3418. results, perhaps with a few more definitions shown.)
  3419.  
  3420. Reverse lookup works with a single word or a phrase up to 255
  3421. characters, and just looks for a match in struct, union and typedef
  3422. definitions regardless of where the text occurs. The most common use
  3423. is to look up a member name, but you can also use it to look up a
  3424. distinctive word or phrase in a comment that you recall seeing, perhaps
  3425. in one of your own “popup notes”, as described in “Looking up your
  3426. notes” later in this chapter.
  3427.  
  3428. As of version 3 of EnterAct, the text you're looking up must begin
  3429. with the start of a word for reverse lookup, but need not end with
  3430. a complete word.
  3431.  
  3432. Tip: type the member name using proper case, and check the AutoLook
  3433. window: it will show a list of all structs, classes, and unions that
  3434. contain that member name. And in most cases you can press <enter>
  3435. instead of <shift><enter> to produce a "reverse lookup" window. The
  3436. only real exceptions are names that are #defined, such as
  3437. #define STANDARD_FIRST_MEMBER long next;
  3438. --in this case you would have to press <shift><enter> after typing
  3439. STANDARD_FIRST_MEMBER if you wanted to see what structures made
  3440. use of it, since pressing <enter> would just show you the definition of
  3441. STANDARD_FIRST_MEMBER. But heck, only IBM and MicroSoft commit
  3442. that sort of barbarism these days....
  3443.  
  3444. §    “Sounds like” lookup (press <Option><Enter>)
  3445. When you can’t remember what case conventions were used for a name,
  3446. or your recollection of the spelling is very very vague, type in your
  3447. best guess and try <Option><Enter> instead of just plain <Enter>. This
  3448. activates “sounds like” or “phonetic” rather than regular lookup. Upper
  3449. and lower case are treated as the same, vowels are used to determine
  3450. what the surrounding consonants sound like, and consonants are
  3451. converted to standard phonetic equivalents in your guess. This “boiled
  3452. down” version of your guess is then compared with similarly boiled-down
  3453. versions of all names in your dictionary, and you will be shown the
  3454. definitions of the ones that come closest in the resulting lookup
  3455. window.
  3456.  
  3457. The different definitions available can be viewed in the same way as
  3458. with regular lookup windows: use <Enter> and <Option><Enter> to cycle
  3459. forwards and back, or <Option>click in the title bar and choose from
  3460. the popup menu.
  3461.  
  3462. Sounds-like lookup should be kept in mind as an “emergency backup”,
  3463. worth trying if regular lookup doesn’t bring up the definition you want
  3464.  
  3465. As an example, suppose you’re after the definition of ParamBlockHeader,
  3466. but misremember it as PARAMHEAD. Regular plain-<Enter> lookup would
  3467. fail in this case, since it is case-sensitive. Pressing <Option><Enter>
  3468. would work, but might also call up spurious matches (who knows what,
  3469. perhaps kPrimeHidden) since it largely ignores vowels. On the other
  3470. hand, if you misremember CopyFile as KoppeePheill then sounds-like
  3471. lookup will work, and I imagine you won’t be complaining about the few
  3472. extra spurious matches that it throws up.
  3473.  
  3474.  
  3475. §    Viewing other entries in lookup windows
  3476. <Enter> and <Option><Enter> take you forwards and backwards through
  3477. the different definitions available in any lookup window, as described
  3478. in the section “<Enter> for lookup, advancing, scrolling” a couple of
  3479. pages back.
  3480.  
  3481. For a quick overview of all entries in the lookup window, hold down
  3482. the <Option> or <Command> key and click (and drag) in the lookup
  3483. window’s title bar. A popup menu will appear, listing the first line
  3484. from each entry (or at least a good part of it), and you can go to the
  3485. entry by selecting it from the menu.
  3486.  
  3487. The first letter in each menu item indicates the type of the entry ('v’
  3488. for variable, ‘(’ for function, ‘#’ for define etc). For details, see
  3489. “Hints with lookup” below.
  3490.  
  3491. (<Option>click-and-drag in the title bar)
  3492.  
  3493.  
  3494.  
  3495.  
  3496.  
  3497.  
  3498.  
  3499.  
  3500. §    For faster lookup
  3501. If lookup on average takes longer than you’re willing to wait when your
  3502. spelling is off, the simplest cure is to trim unneeded files from your
  3503. project, thus reducing the size of your dictionary. See “Project memory
  3504. needs” in the “Projects” chapter for a guide to trimming files, and
  3505. also the document “EnterAct memory needs”. Regular lookup for exact
  3506. spelling is always instant, and reverse lookup nearly so.
  3507.  
  3508.  
  3509. §    Hints with lookup
  3510. (Optional reading, for diehard powerusers)
  3511.  
  3512. When you type in a name and press <Enter>, you know what “kind of
  3513. thing” you want, but EnterAct doesn’t. Supplying EnterAct with a quick
  3514. hint will help speed up the lookup if your spelling doesn’t match an
  3515. entry, and it will in all cases limit the entries that are retrieved
  3516. to the type that you specify with the hint.
  3517.  
  3518. A hint for lookup consists of one character added after the name you
  3519. wish looked up. Normally you’ll need to first type a space and then
  3520. the one–character hint, to separate it from the name. However, the hint
  3521. for a function “(” and the hint for a #define “#” can’t be part of any
  3522. name, so the space is optional for these two.
  3523.  
  3524. Here are the hints you can supply, with examples: in all cases you
  3525. should select an insertion point just to the right of the hint just
  3526. before pressing <Enter> so that EnterAct can pick up the hint
  3527. correctly, or select the word and the hint. For all except the function
  3528. and #define hints, a bit of space (blanks or tabs) between the name
  3529. and the hint is necessary.
  3530.  
  3531. ____
  3532. Type                            Hint     Example
  3533. ----                         ----     -------
  3534. function, method      (          SomeFunc(
  3535. struct, class            s          MyStruct s
  3536. variable                   v          globalVar7 v
  3537. #define                   #          BIGNUM#
  3538. union                       u           IntOrFloat u
  3539. enum                        e          ErrorCodes e
  3540. enum constant         c           eNoMemory c
  3541. typedef                        t          MyStruct t
  3542. ____
  3543.  
  3544. In the display box of a lookup window you will see one of the above
  3545. hints for each entry, between the file name and the current entry
  3546. number. This is just to remind you that EnterAct keeps track of what
  3547. kind of thing each term is, and that it will understand the above hints
  3548. if you supply them.
  3549.  
  3550. When should you supply a hint? Almost never. Perhaps when you have a
  3551. struct, a typedef, and a variable that have very similar names, you
  3552. don’t remember the exact spelling, and you want just one of them
  3553. without the nuisance of the others. Since flipping through lookup
  3554. entries is as fast as pressing the <Enter> key once the lookup appears,
  3555. the only common reason to supply a hint is to speed up the lookup
  3556. process itself. But in this case you should first try trimming
  3557. unnecessary files from your project, as this will also speed things
  3558. up by reducing the size of your dictionary.
  3559.  
  3560. §    Number of lookup windows
  3561. With too many lookup windows on–screen at once, your screen will be
  3562. too cluttered. If too few are available, that will hamper you when you
  3563. have a complicated problem to wrestle with. The upshot is that the
  3564. maximum number of lookup windows on–screen at once must be under your
  3565. control, so you can vary this number as the situation demands. You can
  3566. change this number at any time by typing a new number in the “Number
  3567. of lookup windows” box in the Options dialog. The default number is
  3568. 4, but you can vary it from 1 to 10.
  3569.  
  3570.  
  3571.  
  3572.  
  3573.  
  3574.  
  3575.  
  3576.  
  3577.  
  3578.  
  3579.  
  3580.  
  3581.  
  3582.  
  3583.  
  3584.  
  3585.  
  3586.  
  3587.  
  3588.  
  3589.  
  3590.  
  3591. The “Number of lookup windows” includes any that you mark for keeping
  3592. around, and determines when a lookup window that is not marked for
  3593. keeping around will go away on its own. When you press <Enter>
  3594. to see a new lookup and the lookup window limit has already been
  3595. reached, one of the old lookup windows that was not marked for keeping
  3596. around will quietly go away, and the new one will replace it. There’s
  3597. no predicting which one, so if you want a lookup window to stay up
  3598. until you explicitly close it, select Keep Lookup Around while it is
  3599. the front window ( see “Keeping lookups around” below for details).
  3600.  
  3601.  
  3602. §    Number of entries per lookup
  3603. When your spelling doesn‘t match any term in your dictionary exactly,
  3604. the number of entries that are retrieved in the lookup window is under
  3605. your control. To change this number, select Options and type a new
  3606. number in the “Number of entries per lookup window” box (see
  3607. illustration just above). The default of 4 suits most cases, but you
  3608. may prefer 3 or 5. The maximum of 20 entries is useful only when your
  3609. recollection of the correct spelling has gone right out the window.
  3610.  
  3611. §    Keeping lookups around
  3612. The command for this is under the Windows menu. When you select Keep
  3613. Lookup Around with a lookup window in front, the lookup will be marked
  3614. for keeping around, which is to say it won’t close unless you close
  3615. it yourself. Other lookups not marked for keeping around may quietly
  3616. close when you ask for a new lookup after having hit the limit on the
  3617. number of lookup windows on–screen at one time.
  3618.  
  3619. When you select Keep Lookup Around for a lookup window, the beginning
  3620. of the window title will change from •• to ¶¶ to show you that it is
  3621. marked for keeping. A ¶ is a Paragraph mark, which starts with P, and
  3622. that stands for Permanent.
  3623.  
  3624.  
  3625.  
  3626.  
  3627.  
  3628.  
  3629.  
  3630.  
  3631.  
  3632.  
  3633. A lookup window marked for keeping will close only if you select Close
  3634. or Close All, or close the project, or leave EnterAct. In other words,
  3635. it’s as permanent as a regular text window.
  3636.  
  3637.  
  3638. Since the AutoLook window changes so often, if you want to preserve
  3639. an entry you should look it up in the usual way, by double-clicking
  3640. on or clicking just to the right of the word (or partial word) and
  3641. pressing the <Enter> key. You can do the lookup right in the AutoLook
  3642. window if you wish.
  3643.  
  3644. After you’ve used the AutoLook window for a bit, it serves as a
  3645. spelling checker for terms. If you don’t detect a slight
  3646. flicker in the AutoLook window out of the corner of your eye when you
  3647. type the name of a term that should be in your dictionary, take a
  3648. glance at the AutoLook window—if the definition or prototype isn’t
  3649. there, you have a spelling error.
  3650.  
  3651.  
  3652. §    Looking up your notes
  3653. Here’s how to build your own hard–won notes and observations about
  3654. programming the Macintosh into your dictionary, for quick retrieval
  3655. by name. You might call them “popup” notes, but as you’ll see, they’re
  3656. just a variation on looking up C terms and the notes appear in the
  3657. AutoLook window or a regular lookup window.
  3658.  
  3659. Note files consist of fake C constructs, the sole content of each
  3660. construct being a comment which contains the specific note. Suppose,
  3661. for example, one of your notes concerns the modification date
  3662. (“modDate”) for a file. To be able to retrieve the note, you first need
  3663. to think of a memorable name for it, such as “modDateNote”. Then, in
  3664. your note file, you would set up the dictionary entry like this:
  3665. ____
  3666. struct modDateNote
  3667.     {
  3668.     /*
  3669.     Paste the note in here, within a comment
  3670.     that makes up the entire "struct" body.
  3671.     */
  3672.     };
  3673. ____
  3674. The note goes inside a comment, which makes up the body of a struct.
  3675. Placing the note inside a comment is necessary, to prevent the
  3676. dictionary builder from trying to interpret your text as C code. There
  3677. are other constructs you can use, such as
  3678. ____
  3679.     #define modDateNote /*
  3680.      Paste the note in here, within a comment
  3681.      that makes up the entire "define" body.
  3682.     */
  3683. or
  3684.     int modDateNote /* your note here
  3685.         in a comment */;
  3686. ____
  3687. but a struct is definitely the best, since reverse lookup can then be
  3688. used to retrieve a note based on some distinctive word or phrase that
  3689. it contains.
  3690.  
  3691. Since notes are always placed inside C comments, you should avoid C
  3692. comment starts and ends (/* and */) within the note itself.
  3693.  
  3694. It remains only to persuade EnterAct to build such a file into your
  3695. dictionary. EnterAct will do so for files that are in the left or
  3696. middle pane of your project, and by default if a file name ends in “.c”
  3697. or “.h” etc it is added to the left or middle pane respectively. However,
  3698. a slightly nicer approach is to give your note files an ending that
  3699. describes what they are. A reasonable choice would be “Notes”, and then
  3700. your note files would have names like “File.Notes”, “Memory.Notes”,
  3701. “Interface.Notes”. To instruct EnterAct that files with names ending
  3702. in “Notes” should go in the left or middle pane, select the File
  3703. Extensions command and type in the file extension (eg “Notes”) that
  3704. you choose for your note files—see the “Custom file extensions” section
  3705. in the “Projects” chapter for an example. Which pane these files go
  3706. in (left or middle) is up to you. Using a custom extension rather than
  3707. the default “.c” or “.h” for your note files will also help prevent
  3708. confusion if other people examine your work.
  3709.  
  3710. Now add the note files to your project, select Update Dictionary, and
  3711. you can retrieve any note to the AutoLook window by typing its name
  3712. in any text window, and pressing <Enter> will place the note in a
  3713. separate new lookup window. If the name of the note consists of the
  3714. exact topic followed by “Note” then it will be easy to remember. And
  3715. if you place a comment in your source code containing the name of the
  3716. note, such as     /* see modDateNote */ 
  3717.  
  3718. then all you have to do is double-click on the note name (and press
  3719. <Enter> if you want a more permanent view than the one shown in the
  3720. AutoLook window).
  3721.  
  3722. A note can be of any length, and if you edit it heavily you can
  3723. probably clean up the appearance afterwards with Reformat Selection.
  3724.  
  3725. For an example of a note file, see the file “hAWK_notes.h” on disk 2.
  3726. As a specific example,
  3727. ____
  3728.     if ((**availRgn).rgnSize > 10) /* see RegionNote */
  3729.         {
  3730.         yPos = 5;
  3731.         y = *(((int *)(*availRgn)) + yPos);
  3732.         while (y != 32767)
  3733.             {
  3734.             xPos = yPos + 1;
  3735.             ...etc
  3736. ____
  3737. might look like Greek to me if I come back to review it, but by
  3738. clicking to the right of RegionNote  in the comment and pressing
  3739. <Enter> I can view my hard–won note on regions that explains in more
  3740. detail what’s going on:
  3741.  
  3742.  
  3743.  
  3744.  
  3745.  
  3746.  
  3747.  
  3748.  
  3749.  
  3750.  
  3751.  
  3752.  
  3753.  
  3754.  
  3755.  
  3756.  
  3757.  
  3758.  
  3759. Often it’s simpler to just place a “go to” link in your code
  3760. (consisting of a file name followed by a marker name, as detailed in
  3761. the “‘Go’ commands” chapter). “Go to” links have two advantages over
  3762. popup notes: any text in any document, including support documents,
  3763. can be marked for use a link, and the text at the link can include
  3764. illustrations. But “popup” notes as described above have two advantages
  3765. over “go to” links: they appear in politely placed and sized windows,
  3766. as do all lookup windows, and you can view several notes from the same
  3767. file in separate windows. A mix of “Go to” links to access existing
  3768. or complex documents, and popup notes to retrieve details on specific
  3769. programming tasks might be best.
  3770.  
  3771. §    EnterAct as a "definition finder" for other editors
  3772. To use EnterAct as a "definition finder" with other editors:
  3773.     •    read enough here to learn how to create a project, build
  3774.     a dictionary, and show the "AutoLook" window. Knowing
  3775.     how to call up "lookup" windows by pressing the <Enter>
  3776.     key is also useful.  That's all above here.
  3777.     •    when you're using the other editor, also run an EnterAct
  3778.     project with contents roughly corresponding to the code
  3779.     you're working on - have the "AutoLook" window open,
  3780.     as the frontmost text window in EnterAct. Your project
  3781.     dictionary should be reasonably up to date.
  3782.     •    to look up a term with EnterAct; Copy it in the other editor,
  3783.     and switch to EnterAct. If you don't immediately see the
  3784.     definition in the AutoLook window (rare), press
  3785.     <Command><Enter>. To look up the class or struct that
  3786.     contains a particular member, press <Shift><Command><Enter>.
  3787.  
  3788. §    Looking it up with THINK Reference or Toolbox Assistant
  3789. You'll see "Find in THINK Reference" and "Find in Toolbox Assistant"
  3790. under EnterAct's Search menu: to get them working, create a folder
  3791. named "Tools" or "(Tools)" next to EnterAct at the same level, and
  3792. drop aliases of THINK Reference and QuickView into it. When you
  3793. want to look something up, either select a term or click just after
  3794. it and issue the appropriate menu command (the command key
  3795. equivalents <Command><-> and <Command><4> are worth memorizing).
  3796.  
  3797.  
  3798. -    -    -    -    -    -    -    -    -    -    -    -
  3799. Seeing where a term is defined
  3800. -    -    -    -    -    -    -    -    -    -    -    -
  3801. §    <Option>double–click
  3802. To see the file in which any dictionary term is defined, hold down the
  3803. <Option> key while double–clicking on the term. EnterAct will enter
  3804. the term in the Find dialog (the equivalent of Enter Selection), open
  3805. the file where the term is defined, and scroll to the first instance
  3806. of the term in the file.
  3807.  
  3808. Except for functions, methods, structs, classes, unions, and enums,
  3809. for which you’ll almost always be scrolled to the exact defining
  3810. instance, with no tripping over a mention in a comment or variable
  3811. declaration or prototype.
  3812.  
  3813. (Note you can look up the definition of a full method name, in the
  3814. format "class_name::method_name", by <Option>double-clicking
  3815. on the class name, dragging over to the method name to select it
  3816. as well, and then releasing the mouse. Or if you prefer you can
  3817. look it up by selecting both names and then using the Find
  3818. Definition command.)
  3819.  
  3820. Here's an example of looking up a class definition:
  3821.  
  3822.  
  3823.  
  3824.  
  3825.  
  3826.  
  3827.  
  3828.  
  3829.  
  3830.  
  3831.  
  3832.  
  3833.  
  3834.  
  3835.  
  3836.  
  3837.  
  3838.  
  3839.  
  3840.  
  3841.  
  3842.  
  3843.  
  3844.  
  3845.  
  3846.  
  3847. (those are old-style window, but the idea is the same....)
  3848.  
  3849. If you are viewing just a method name, without the class name:
  3850.     •    bring up your AutoLook window (you'll find it's useful all the
  3851.         time)
  3852.     •    click after or double-click on the method name in your source
  3853.         window
  3854.     •    AutoLook will show a complete list of prototypes for the method
  3855.         name
  3856.     •    select the one you want, class name and method name inclusive,
  3857.         in the AutoLook window and use Find Definition
  3858.     •    or <Option>double-click on the class name, drag to the method
  3859.         name, and release the mouse
  3860.  
  3861. For example, to view the definition of "DoSpecificCommand" in
  3862. the class "TFaxPage", when viewing just
  3863. "someObject->DoSpecificCommand(1,2)", you would click just
  3864. after "DoSpecificCommand" to see the following in the
  3865. AutoLook window:
  3866. ____
  3867.     OSErr TFaxDocument :: DoSpecificCommand
  3868.         (short     stdCommandNumber,
  3869.         long    misc)
  3870.         
  3871.     OSErr TFaxEdit :: DoSpecificCommand
  3872.         (short     stdCommandNumber,
  3873.         long    misc)
  3874.         
  3875.     OSErr TFaxPage :: DoSpecificCommand
  3876.         (short     stdCommandNumber,
  3877.         long     misc)
  3878. ____
  3879. --then select "TFaxPage :: DoSpecificCommand", and use the
  3880. Find Definition command to jump to the definition. Or <Option>
  3881. double-click on one of the words, drag to the other, and release
  3882. the mouse.
  3883.  
  3884. If your spelling of the method name is off, and nothing shows in the
  3885. AutoLook window, click just after your guess at the name and press
  3886. <Enter>. If your guess was close enough, the resulting lookup window
  3887. will hold entries for all methods with the correct name. Hold down
  3888. the <Option> key and click in the title bar of the lookup window to
  3889. view a list of the methods -- if you see the right one, select it,
  3890. and your desired one will appear in the body of the lookup window,
  3891. where you can <Option>double-click or use Find Definition.
  3892.  
  3893. §    Find Definition
  3894. Find Definition is useful with parts of a word (such as just the
  3895. WindowData  part of WindowDataPtr )—just select the exact term you want
  3896. to view the defining instance of, without regard for what comes before
  3897. or after it.
  3898.  
  3899. Find Definition ignores trailing spaces or tabs, and also accepts hint
  3900. characters in much the way that lookup does.
  3901.  
  3902.  
  3903. §    If there are multiple definitions
  3904. If you have several methods with the same name, use the
  3905. AutoLook window to pick the right one as described just above.
  3906.  
  3907. In the general case, you can jump to a particular definition of a
  3908. term as follows:
  3909.     •    select the term or click after it, and press <Enter> to look it up
  3910.     •    in the resulting lookup window, hold down the <Option> key and
  3911.         click in the window's title bar to view a popup menu listing all the
  3912.         definitions and abbreviated full path names for their locations
  3913.     •    pick the one you want, then <Option>double-click on the term
  3914.         as shown in the lookup window.
  3915.  
  3916. If the term is a static function or variable and you happen to be
  3917. viewing the file where it is defined, then <Option>double-clicking
  3918. on the name anywhere in that file will take you to the definition
  3919. in that same file.
  3920.  
  3921. Note if you want a list of all definitions of a term, the simplest
  3922. way is still to do a Batch Find, then trim the results.
  3923.  
  3924. §    Other ways of finding definitions
  3925. The AutoLook window will display definitions instantly when you select
  3926. or click after a term, greatly reducing the need to “find” definitions.
  3927. It will also show most class method definitions, and definitions for
  3928. data members (these details are subject to last-minute improvements).
  3929. And of course you can retrieve the definition of a term to a separate
  3930. lookup window by clicking after the term and pressing the <Enter> key.
  3931.  
  3932. “Go to” links, as explained in the “‘Go’ command” chapter, can be used
  3933. to jump to any marked location in any file. This includes function and
  3934. method definitions  if you are using Automark to mark your source files
  3935. in the default way.
  3936.  
  3937. The "Cross-Reference" index command (chapter 22) can generate a
  3938. cross-reference of C (only) terms in your source code that is compatible
  3939. with EnterAct’s "Go to" command. These “file-name line-number”
  3940. references can go out of date if you edit your files, but are handy
  3941. for files that don’t change often.
  3942.  
  3943. -    -    -    -    -    -    -    -    -    -    -    -
  3944. Browsing
  3945. -    -    -    -    -    -    -    -    -    -    -    -
  3946. §    The Browse command
  3947. The window produced by this command shows a “family tree” of the
  3948. classes in your project, as of your last dictionary update, and also
  3949. allows you to quickly view any class or method definition. It will
  3950. close when you close your project, and will update automatically when
  3951. you update your project dictionary.
  3952.  
  3953. In the browser, "user"-defined class names are underlined, whereas
  3954. <system>-defined classes are not.
  3955.  
  3956. The solid black horizontal and vertical lines connect each child to
  3957. the first of its parents. If a class inherits from multiple parents,
  3958. light colored lines connect the middle of each parent to the left or
  3959. right end of each child. For example, given
  3960. ____
  3961.     class A : B, C, D {...
  3962. ____
  3963. you would find in the browser window a set of solid horizontal and
  3964. vertical lines connecting A to B, and light colored lines would connect
  3965. the middles of C and D to the left or right end of A.
  3966.  
  3967. If a class contains other classes or structs as members, they will
  3968. be listed beneath the class name, separated from it by a white line.
  3969.  
  3970. To view the definition of a class, double–click on the class name. This
  3971. works much like <Option>double-click or Find Definition in a text
  3972. window. This works with both a "main" class name and any of its
  3973. member class or struct names.
  3974.  
  3975. To view a method definition, click and hold on the owning class name:
  3976. after a brief pause (your double–click time, actually) a popup menu
  3977. will appear listing all of the class’s methods. You should then select
  3978. the method you want and release the mouse button, as if you hadn’t
  3979. guessed. This also works with member class names (as of this
  3980. writing, it's untested with member struct names.)
  3981.  
  3982. To view a popup of all methods in a class AND all methods that
  3983. it inherits, hold down the <Command> key and click and hold on
  3984. the class name. This list can be quite long, and may take several
  3985. seconds to generate--please be patient the first few times you
  3986. try it. Inherited private methods are not shown, and virtual methods
  3987. are indicated with a "v" before the name.
  3988.  
  3989. If your family tree of classes involves a great deal of multiple
  3990. inheritance, the many light colored lines may become too tangled to
  3991. decipher, and even obscure class names. To display just the colored
  3992. inheritance lines for one class, click once on the class name (all
  3993. colored lines not connecting to the class will disappear). To add
  3994. lines for other classes, click on the class names with the <Shift>
  3995. key held down. Similarly, you can suppress the colored lines for one
  3996. class by <Shift>clicking on it. To show all colored lines again, click
  3997. once on the white background between classes. Double-clicking to
  3998. show a class definition does not suppress any colored lines, and neither
  3999. does the click-and-hold to view a method popup.
  4000.  
  4001. Instead of trying to follow the colored lines, you can view the parents
  4002. of a main class by holding down the <Option> key and
  4003. clicking on its name to view a popup of mom and pop etc. Note that
  4004. releasing the mouse over one of the parents will take you to its
  4005. definition, a feature I included mainly because a popup is supposed
  4006. to do something.
  4007.  
  4008. Classes without proper parents (orphans, if you like) will always
  4009. appear in the left–most column of your browser window. A quick look
  4010. down the left column will reveal whether you have any unintentional
  4011. orphans, perhaps due to misspelling the parent class name in the class
  4012. definition. 
  4013.  
  4014.  
  4015.  
  4016.  
  4017.  
  4018.  
  4019.  
  4020.  
  4021.  
  4022.  
  4023.  
  4024.  
  4025.  
  4026.  
  4027.  
  4028.  
  4029.  
  4030.  
  4031.  
  4032.  
  4033.  
  4034.  
  4035.  
  4036.  
  4037.  
  4038.  
  4039.  
  4040.  
  4041. (Note EnterAct works fine with CodeWarrior etc classes, for which
  4042. there may be many base classes in the leftmost column.)
  4043.  
  4044. §    Finding classes in the Browser window
  4045. To bring a particular class into view, type the first part or some
  4046. distinctive part of its name. The name will flash once.
  4047.  
  4048. You can also use the Find dialog and the Find Again command to
  4049. find classes in the browser window (eg if you're looking at the
  4050. source for a class and want to see where the class is in the
  4051. browser, use Enter Selection to enter the class name in the Find
  4052. dialog, then bring the browser to the front and do a Find Again).
  4053.  
  4054. §    Method and class popups
  4055. (This is a summary of popups, as described above)
  4056.     • to view the methods associated with a class, click and hold
  4057.     on the class name.
  4058.     • to view all inherited methods as well, hold down the <Command>
  4059.     key while you click and hold on the class name. If the list is
  4060.     gigantic, it may take several seconds to generate the popup, so
  4061.     please be patient the first few times you try this.
  4062.     • to view a list of the immediate parents of a class, hold down
  4063.     the <Option> key while you click and hold on the class name.
  4064.  
  4065. §    Browsing classes without the browser
  4066. Nothing new to seeing class definitions—click to the right of the class
  4067. name and press <Enter>, or just look in the AutoLook window.
  4068. You will typically find the class name of an object as the first name
  4069. in the statement where it is defined, as in
  4070. ____
  4071.     TClassName        *objectName;
  4072. ____
  4073. You can also, of course, look up a class by typing the name and
  4074. pressing <Enter>, and in all cases your spelling just needs to be
  4075. reasonably close, not exact. In either case, the definition will appear
  4076. in the AutoLook window if you have it open.
  4077.  
  4078.  
  4079. §    Browsing methods without the browser
  4080. (The approach below is for use when your spelling of a method
  4081. name is incorrect, or the owning class is determined at runtime.
  4082. If your spelling is correct or the class is "fixed", you will see
  4083. the appropriate prototype in the AutoLook window when you
  4084. click after or double-click on the method name. To go to the
  4085. definition, select the full "class_name::method_name" in the
  4086. AutoLook window, then use the Find Definition command, or
  4087. <Option>double-click, dragging to select both names before
  4088. releasing the mouse.)
  4089.  
  4090. Method browsing is a bit trickier, since if you have something like
  4091. ____
  4092.     "currentObject->Draw();"
  4093. ____
  4094. and there are several different classes with Draw() methods, then
  4095. EnterAct does not know specifically which Draw() method you want. If
  4096. there is only one method in your project with a given name, then the
  4097. lookup window will contain just one entry, but if there are several
  4098. then the lookup window will contain all of them (up to a maximum of
  4099. 60). For example, if you were to press <Enter> with an insertion point
  4100. to the right of Draw above, then the lookup window might contain
  4101. entries for void Circle::Draw(), void Square:: Draw(), void
  4102. Oval::Draw() and so on. When there are several entries like this, you
  4103. can cycle through them by pressing the <Enter> key, and back up by
  4104. pressing <Option><Enter>. There are some illustrations of this just
  4105. ahead.
  4106.  
  4107. This raises the question of how to find where a method is defined. The
  4108. general approach is described in the chapter “Seeing where a term is
  4109. defined”, but the approach for a method has one extra step:
  4110.     •    double-click on the method name, and a list of all methods with that
  4111.         name will appear in the AutoLook window;
  4112.         or, press <Enter> and cycle through the lookup window until
  4113.         you find the method you want, based on the name of the owning class
  4114.     •    then select the entire name, consisting of the owning class name,
  4115.         the two colons, and the method name, in general
  4116.         className::methodName
  4117.     •    and then select Find Definition.
  4118.     •    (or <Option>double-click, ya ya you know already)
  4119.  
  4120. There is one exception to this: if there is only one method in your
  4121. project with the name in question, then a standard <Option>
  4122. double–click on just the method name will jump you to the file where
  4123. that method is defined. However, if there are several methods with the
  4124. same name  in different classes, there’s no predicting which definition
  4125. you will see if you just <Option> double–click on the method name—best
  4126. to look up the method first, and use Find Definition on the full name
  4127. of the exact one you want.
  4128.  
  4129. By the way, when viewing the full “className:: methodName” of a method,
  4130. you can look up the definition of the owning class of the method by
  4131. clicking at the right end of the class name, before the colons, and
  4132. pressing <Enter>. If the instance of the method name you’re viewing
  4133. doesn’t have the class name attached, look up the method name as
  4134. decribed just above to see the full method name including the owning
  4135. class, and then do your lookup for the class in the lookup window shown
  4136. for the method.
  4137.  
  4138. If you want to see where a method is defined, but can’t remember the
  4139. exact spelling of the name, type your best guess and press <Enter>.
  4140. The true name you wanted will probably be among the first few entries
  4141. in the lookup window, and then you can proceed with an <Option>
  4142. double–click or Find Definition right in the lookup window to get to
  4143. the file you want to see.
  4144.  
  4145. If you want lookup for a method when you’re not sure of the spelling,
  4146. and want to restrict the lookup to just methods, type a bit of the
  4147. class name and two colons just before the method name—even C::method
  4148. will do (even if the class name doesn’t contain a “C”—it’s the two
  4149. colons which signal that a method is wanted).
  4150.  
  4151. EnterAct is not a fancy bells–and–whistles browser, but it does allow
  4152. you to look everything up quickly. And, it has two advantages over any
  4153. other browser: your code doesn’t have to be perfectly compilable, just
  4154. reasonably close; and your spelling when you want lookup for anything
  4155. (including methods and classes) doesn’t have to be perfect, just close
  4156. enough to be distinctive. Try that on your SmallTalk!
  4157.  
  4158.  
  4159. A method-browsing example:
  4160.  
  4161. Here we've typed "EstablishPort" in a new window, and then pressed
  4162. the <enter> key: the corresponding lookup window holds entries for
  4163. all EstablishPort methods. The cursor is caught in the act of
  4164. <option>clicking in the title bar of the lookup window to select
  4165. the entry for LOffscreenView::EstablishPort.
  4166.  
  4167.  
  4168.  
  4169.  
  4170.  
  4171.  
  4172.  
  4173.  
  4174.  
  4175.  
  4176.  
  4177.  
  4178.  
  4179.  
  4180.  
  4181.  
  4182.  
  4183.  
  4184.  
  4185.  
  4186.  
  4187. After the LOffscreenView::EstablishPort appears in the lookup window,
  4188. <option>double-clicking on it takes us to its definition.
  4189.  
  4190.  
  4191.  
  4192.  
  4193.  
  4194.  
  4195.  
  4196.  
  4197.  
  4198.  
  4199.  
  4200.  
  4201.  
  4202.  
  4203.  
  4204.  
  4205.  
  4206.  
  4207.  
  4208.  
  4209. -    -    -    -    -    -    -    -    -    -    -    -
  4210. Documents and windows
  4211. -    -    -    -    -    -    -    -    -    -    -    -
  4212. §    New, Open, Close
  4213. New under the File menu means a new text window. To create a project,
  4214. select New Project from the EnterAct menu. A new lookup window appears
  4215. automatically whenever you look something up. New PICT windows can’t
  4216. be had, no matter what you try.
  4217.  
  4218. Open under the file menu allows you to open any TEXT or PICT document.
  4219. To open a project, select Open Project from the EnterAct menu. 
  4220.  
  4221. Close will close the front window, whatever it is, and the key
  4222. equivalent <Command><W> is often handy. Close Project will close the
  4223. project window whether it is in front or not. Only one project can be
  4224. open at a time, so if you select Open Project while a project is open
  4225. you will be asked to confirm putting away the current project. The same
  4226. applies if you select New Project.
  4227.  
  4228. To close all text windows, select Close All from the Windows menu. This
  4229. will not close your project or the Find dialog.
  4230.  
  4231. EnterAct provides some support for unix and DOS files. Specifically,
  4232. you can open, change, and save them, and change from one type to
  4233. the other using the little popup menu at bottom-left of the windows.
  4234.  
  4235.  
  4236. §    Save, Save As, Revert
  4237. Save applies only to proper text documents (not lookup windows) and
  4238. to PICT’s. Saving a PICT will alter only the window location that
  4239. EnterAct saves with any file. To save the contents of a lookup window,
  4240. Copy what you want and Paste it into a regular text window. Projects
  4241. are saved automatically, when you update the dictionary, add files,
  4242. or close the project. 
  4243.  
  4244. Save As can be used with text and PICT documents, and with a project
  4245. as well. In particular, you can set up a project to use as
  4246. “stationery”, with the font and window location preset, and commonly
  4247. needed files already added—for details see the “Projects” chapter,
  4248. section “Creating a project”.
  4249.  
  4250. Revert applies to text and PICT documents only (with PICT’s only the
  4251. position on your screen is reverted).
  4252.  
  4253. §    Close and Save Documents
  4254. These two new commands are under the Windows menu, supplementing
  4255. the old Close All and Save All. The Close Documents and Save
  4256. Documents commands affect only windows which already have a
  4257. corresponding file on disk: in particular, “untitled” windows are left
  4258. alone. By contrast, Close All also closes lookup windows and asks you
  4259. to save any “untitled” windows—and Save All also asks you about
  4260. saving “untitled” windows.
  4261.  
  4262. §    Autorevert
  4263. When you select Autorevert for an open document, EnterAct will check
  4264. the disk file for the document every 10 seconds, and refresh the
  4265. document’s window if the contents of the file have changed. This
  4266. continues until you select Autorevert for the document again (it’s a
  4267. toggle) or until you close the window. To remind you that the
  4268. document’s window is being autoreverted, a “disk-to-window” icon will
  4269. be shown in the window’s display box.
  4270.  
  4271.  
  4272.  
  4273.  
  4274.  
  4275. Typically EnterAct will not detect that a file has been changed until
  4276. it is closed by the program that is changing it.
  4277.  
  4278. While implemented in a general way, Autorevert is primarily meant for
  4279. use with hAWK programs that print ongoing progress messages to disk.
  4280. Several of the supplied hAWK programs print messages to the file
  4281. “$tempProgress”, and by monitoring this file via Autorevert you can
  4282. watch how programs are progressing as they run. For more on this use
  4283. of Autorevert see Appendix 2.
  4284.  
  4285. Every decent app needs one nutty gizmo. Hence Autorevert.
  4286.  
  4287. §    Modify Read Only
  4288. EnterAct watches out for Projector 'ckid' resources, and won't let you
  4289. change a file if it has been checked out of SourceServer as
  4290. "read only". When a document can't be changed for this reason, a small
  4291. pencil with a slash through it will be shown in the display box of
  4292. its window.
  4293.  
  4294. When you need to edit a file that has been checked out as "read only",
  4295. select "Modify Read Only" from the File menu. This makes the file
  4296. fully editable, and alters the 'ckid' resource slightly so that
  4297. SourceServer will know the file has been changed when you check
  4298. it back in. "Editable" meaning you can change the text in the window
  4299. and save the changes, just as with a regular document.
  4300.  
  4301. No icon is displayed for "modifiable read only" files, mainly because
  4302. your author can't figure out what the heck that means. Whatever
  4303. else it does, it severely compromises version control.
  4304.  
  4305. If you want to ignore 'ckid' read-only stuff altogether because it
  4306. doesn't apply to you, deselect the "Ignore 'ckid's" option in the
  4307. Options dialog (see illustration just below).
  4308.  
  4309.  
  4310. §    Saving window locations
  4311. Saving window locations is nice, provided you aren’t pestered all the
  4312. time to save your changed location when you close a window. In
  4313. EnterAct, saving window locations takes the place of neatly tiling and
  4314. stacking windows. By default, EnterAct will save window locations
  4315. whenever you save a text or PICT document. If you would rather not have
  4316. window locations saved, call up the Options dialog and uncheck the
  4317. “Save document window locations” item. Any saved locations will also
  4318. be ignored when a document is opened if you uncheck this item.
  4319.  
  4320.  
  4321. §    ... without being pestered
  4322. Beneath the “Save document window locations” item in the Options dialog
  4323. there’s another check box, “...but don’t pester me about saving
  4324. locations”. Both of these options are on by default. The “don’t pester”
  4325. part means that you will not be asked if you wish to save a text window
  4326. when you close it if all you’ve done is change the window’s location
  4327. on the screen. 
  4328.  
  4329. The location of the project window is always saved (this is automatic)
  4330. regardless of your options.
  4331.  
  4332.  
  4333.  
  4334.  
  4335.  
  4336.  
  4337.  
  4338.  
  4339.  
  4340.  
  4341.  
  4342.  
  4343.  
  4344.  
  4345.  
  4346.  
  4347.  
  4348.  
  4349.  
  4350.  
  4351.  
  4352.  
  4353. §    Newly opened windows can be long or short
  4354. If the “Save document window locations” item in the Options dialog has
  4355. a check mark, and if a document you open has a window location saved
  4356. with it, then EnterAct will restore your document to its saved
  4357. location. Otherwise, EnterAct won’t have a remembered location for the
  4358. window, or will ignore it (this is especially true of a new text
  4359. window). You can roughly control the length of these windows with the
  4360. radio button options “Windows open short / long by default” in the
  4361. Options dialog. Long windows will reach all the way to the bottom of
  4362. your main screen when they open. Short windows will indeed be
  4363. relatively short on a large screen, but will fill most of a small
  4364. screen.
  4365.  
  4366. The default is short windows. Note that you can grow just the length
  4367. of any text window down to the bottom of the screen by holding down
  4368. the <Option> key while clicking in the zoom box. And it won't cover up
  4369. your AutoLook window.
  4370.  
  4371. The default width of a new window is fixed at a moderate size, about
  4372. 74 characters in Monaco 9 (this is also a near–maximum nice width for
  4373. printing). For existing documents, the width will be based on the first
  4374. 20 lines of the text, within reasonable limits.
  4375.  
  4376. Note that if a document is being opened during restoration of a
  4377. project’s context its location will be where you last left it, not
  4378. necessarily the same as where you last saved it.
  4379.  
  4380.  
  4381. §    <Option>–Zoom zooms just the length
  4382. If you hold down the <Option> key while clicking in the zoom box of
  4383. a window, only the length will be affected. If you’re zooming out (the
  4384. first zoom is usually an “out”), the bottom of the window will drop
  4385. down to the bottom of your screen, rather in the way a menu drops down.
  4386. Zooming in is not affected by the <Option> key. 
  4387.  
  4388. The window you're zooming will stop short of covering your AutoLook
  4389. window if it's in the way.
  4390.  
  4391.  
  4392. §    Number of windows at one time
  4393. Restrictions on the maximum number of windows on–screen at one time
  4394. are as follows:
  4395.  
  4396. ____
  4397. regular text, PICT    memory-limited
  4398. lookup                        10 or fewer (see below)
  4399. project, Browser, AutoLook, Find - one of each at a time.
  4400. ____
  4401.  
  4402. Note you can print any number of EnterAct  text files by selecting them
  4403. in the Finder and then selecting the Finder’s print command, since the
  4404. files will be opened, printed, and closed one at a time.
  4405.  
  4406. While the hard upper limit on lookup windows is 10, you can set the
  4407. maximum number on–screen to any number between 1 and 10 using the
  4408. Options dialog. The default number is 4.
  4409.  
  4410.  
  4411. §    The Windows menu
  4412. Consisting of: Close All, Close Documents, Save All, Save Documents,
  4413. Keep Lookup Around, and a list of your open windows, with the project
  4414. first and others in order from front to back on your screen.
  4415.  
  4416. Close All affects text, lookup, and PICT windows. If it needs saving,
  4417. you’ll be asked. Lookup windows will be quietly closed, since they
  4418. cannot be saved. The combination of Close All with remembered window
  4419. locations lets you arrange groups of documents to work with at one
  4420. time, and switch between groups with a minimum of nuisance.
  4421.  
  4422. Save All will save any text or PICT documents that need it (note lookup
  4423. windows aren’t saveable). If a text window hasn’t been saved yet,
  4424. you’ll see the standard Save As dialog. If you use MultiFinder or
  4425. System 7, and you decide to switch off the “Safe switching under
  4426. MultiFinder” option in the Options dialog, I would strongly recommend
  4427. that you use Save All or preferably Close All before switching to
  4428. another application.
  4429.  
  4430. Close Documents and Save Documents do the same as the Close and
  4431. Save All versions, but affect only documents, ie windows that
  4432. correspond to an existing disk file.
  4433.  
  4434. Keep Lookup Around applies only to lookup windows. The maximum number
  4435. of lookup windows on–screen is fixed (although you can change this
  4436. number at any time in the Options dialog), and when this limit is
  4437. reached the next lookup window that you call up will quietly close one
  4438. of the old lookup windows to make room. To avoid having a particular
  4439. lookup window disappear later on you, select Keep Lookup Around when
  4440. the lookup window is in front. The two bullets •• at the beginning of
  4441. the lookup window’s title will change to ¶¶, showing that it won’t go
  4442. away until you yourself close it. Note especially that Close All will
  4443. close all lookup windows, whether or not they are marked for keeping.
  4444.  
  4445. To bring a window to the front, select it by name from the lower part
  4446. of the Windows menu. If a project is open, it can always be brought
  4447. to the front with the menu key–equivalent <Command><zero>, which is
  4448. worth memorising. No other windows (except dialogs) have key
  4449. equivalents—if your memory is that good then in my humble opinion you
  4450. don’t need EnterAct in the first place. 
  4451.  
  4452.  
  4453. §    The display box
  4454. All text windows including lookup windows have a small “display box”
  4455. along the bottom in the horizontal scroll bar area. For a regular text
  4456. file this displays the name of the file; in a lookup window it shows
  4457. the name of the file from which the entry was taken, followed by the
  4458. (abbreviated) type of entry, the number of the current entry shown,
  4459. and the total number of entries available in the lookup window.
  4460.  
  4461. When you drag the mouse to select text in a text window, the display
  4462. box will change to show the line number that the mouse is currently
  4463. on, followed by the number of characters selected. If more  than one
  4464. line is selected, the display box will show the number of lines
  4465. selected rather than the current line number. To determine how many
  4466. lines there are in a file, use <Option><down arrow> or Go Bottom and
  4467. click on the last line of the file. To determine the number of
  4468. characters in a file, click at one end of the file and then
  4469. <Shift>click at the other end of the file.
  4470.  
  4471. A selection on one line, line number displayed:
  4472.  
  4473.  
  4474.  
  4475.  
  4476.  
  4477.  
  4478.  
  4479.  
  4480. A selection on several lines, number of selected lines displayed:
  4481.  
  4482.  
  4483.  
  4484.  
  4485.  
  4486.  
  4487.  
  4488.  
  4489. The little popup with "M" in it at bottom-left of the window allows
  4490. you to change the file format:
  4491.  
  4492.  
  4493.  
  4494.  
  4495.  
  4496.  
  4497.  
  4498.  
  4499.  
  4500.  
  4501.  
  4502. (as of v3.7.8 there is a command to turn coloring on and off in the
  4503. little popup as well).
  4504. §    Printing
  4505. To print a text file, bring its window to the front and select Print.
  4506. A Page Setup beforehand will be needed if you wish to print in a
  4507. nonstandard way, such as sideways or with an unusual paper size. To
  4508. stop a printout, press <Command><period>.
  4509.  
  4510. Printing of PICT’s or other kinds of files is not supported, just text.
  4511. However, any illustrations in a text document (see next section) will
  4512. print properly, with automatic nudging to avoid clipping a picture off
  4513. at the bottom of a page.
  4514.  
  4515. EnterAct does not clip long lines of text, but folds the “hangover”
  4516. back to the left margin on a new line. The line-break is not always
  4517. as good as you yourself would do it, but at least you will never lose
  4518. any characters off the right edge when printing. 
  4519.  
  4520. -    -    -    -    -    -    -    -    -    -    -    -
  4521. Editing
  4522. -    -    -    -    -    -    -    -    -    -    -    -
  4523. §    Introduction
  4524. EnterAct provides all the standard text editing commands, which should
  4525. be familiar from elsewhere (THINK C, for example), and so the emphasis
  4526. in this chapter will be on EnterAct’s editing enhancements. Briefly,
  4527. they are:
  4528.     •    everything that changes a document is undoable one way or another,
  4529.         except Revert. In addition to the usual Undo/Redo under the Edit menu,
  4530.         you can also undo any one of your most-recent thousand activities, and
  4531.         limited file reversion is also available (see the “Show Activities”
  4532.         chapter)
  4533.     •    "code templates": type a template name, press <command><return>,
  4534.         and it expands into the full "template", which can be any old chunk
  4535.         of text. And <command><return> advances you through the template
  4536.     •    Paste Selection Behind combines Copy, switch to the next window,
  4537.         and Paste in one command
  4538.     •    the indentation of your code will commonly be preserved when you
  4539.         Paste or Paste Selection Behind
  4540.     •    the selection in the next–to–front window is shown in a frame,
  4541.         useful with the Paste Selection Behind and Find commands
  4542.     •    Reformat Selection can “pretty up” a comment or selection of text,
  4543.         rebreaking lines to your specified width.
  4544.     •    Syntax coloring, for line comments, strings, and ticks
  4545.     •    Graphic nesting display
  4546.     •    full Drag and Drop for text
  4547.     •    you can paste and delete PICTs in text documents, see
  4548.         "Illustrating your text" near the end of this chapter.
  4549.  
  4550. “Balance”, “Show Activities”, and “Options”, under the Edit menu, are
  4551. described in their own separate chapters later in this manual.
  4552.  
  4553.  
  4554. §    Undo
  4555. EnterAct has one level of undo and redo, via Undo/Redo under the Edit
  4556. menu. The undoable and redoable actions are: typing, Cut, Copy, Paste,
  4557. Paste Selection Behind, Clear (Backspace), Shift Left, Shift Right,
  4558. Reformat Selection, Replace, Replace and Find Again, Replace All,
  4559. and Drag and Drop.
  4560.  
  4561. Revert is not undoable, though discarded changes can often be recovered
  4562. with Show Activities. All other “undoable” changes (such as changing
  4563. the font) can be undone by reusing the same command (such as changing
  4564. the font back).
  4565.  
  4566. Just clicking the mouse or selecting a range of text does not affect
  4567. undo. Changing the window does make the last change temporarily
  4568. undoable, but you can restore the ability to undo the last change by
  4569. bringing the appropriate window to the front again.
  4570.  
  4571. To selectively undo past activities or revert files back past the last
  4572. saved version, see the “Show Activities” chapter. For these purposes,
  4573. EnterAct records your last 10,240 activities in full to disk.
  4574.  
  4575.  
  4576. §    Typing, Cut, Copy, Clear
  4577. “Typing” means hitting a sequence of keys that produces text,
  4578. intermingled with any number of <Backspace>’s. A new typing operation
  4579. begins whenever you change the insertion point or select characters
  4580. and then type something. As with all actions, just changing the
  4581. insertion point or selecting characters does not affect your ability
  4582. to undo—it’s the subsequent change to your text that does it.
  4583.  
  4584. When you type <Return> the resulting new line will have the same
  4585. indentation as the line above it, unless you hold down the <Option>
  4586. key, in which case you’ll end up flush at the left margin.
  4587.  
  4588. Cut and Copy are as you would expect, but there is one special feature:
  4589. if you want to take a screen-shot in EnterAct, first Copy a single
  4590. character, and then immediately after taking the screen-shot paste it
  4591. into your scrapbook.
  4592.  
  4593. As an aside, please see "EnterAct's magic clipboard" for a way to run
  4594. hAWK programs on whatever you Copy with EnterAct. The basic 
  4595. sequence is: you write the hAWK program you need, and start it
  4596. running; and then whenever you need the program's results, Copy
  4597. some text to give it the appropriate input, and Paste the results.
  4598. Typically the menu bar will flash to show that your program has
  4599. done something with the current clipboard's contents (this and
  4600. all other aspects of the program are under your control). This
  4601. effectively gives you programmable Copy/Paste using what has
  4602. been called the best little language in the world, and some example
  4603. programs are provided to get you going.
  4604.  
  4605. "Clear" has the same effect as the <Clear> key, and <Backspace> is also
  4606. the equivalent of a Clear if a range of text is selected. If no text
  4607. is selected, <Backspace> will delete one character, whereas Clear will
  4608. not.
  4609.  
  4610.  
  4611. §    Paste preserves indentation
  4612. At least, it does if the range of text you select to be pasted over,
  4613. or the insertion point for the paste, satisfies the requirement: “all
  4614. tabs or spaces to the left at the start”. Also, the text must have been
  4615. cut or copied with EnterAct.
  4616.  
  4617. “All tabs or spaces to the left at the start” means that the first
  4618. character you select for replacement should be the first character on
  4619. the line that is not a space or tab. If you have just an insertion
  4620. point for the Paste, then the same applies—there should be nothing but
  4621. spaces and tabs from the insertion point to the left margin. Starting
  4622. at the left margin will also do.
  4623.  
  4624. The basic rule is you shouldn’t “see” any printing characters between
  4625. the left margin and the start of your selection or insertion point.
  4626. If this rule is satisfied when you are about to Paste, then the paste
  4627. will preserve your relative indentation, removing the need to Shift
  4628. Left or Shift Right afterwards.
  4629.  
  4630. About the only special action you should take to have Paste preserve
  4631. your indentation is to open up a new line with a <Return> just before
  4632. you paste in a block of code, which you probably do anyway.
  4633.  
  4634. A selection with all tabs/spaces to the left at the start:
  4635.  
  4636.  
  4637.  
  4638.  
  4639.  
  4640.  
  4641.  
  4642.  
  4643.  
  4644.  
  4645.  
  4646.  
  4647.  
  4648.  
  4649.  
  4650.  
  4651.  
  4652. The cursor positioned on a blank line, tabbed in the appropriate
  4653. amount, just before pasting in the above selection:
  4654.  
  4655.  
  4656.  
  4657.  
  4658.  
  4659.  
  4660.  
  4661.  
  4662.  
  4663.  
  4664.  
  4665.  
  4666.  
  4667.  
  4668.  
  4669.  
  4670. After the paste (no shifting needed):
  4671.  
  4672.  
  4673.  
  4674.  
  4675.  
  4676.  
  4677.  
  4678.  
  4679.  
  4680.  
  4681.  
  4682.  
  4683.  
  4684.  
  4685.  
  4686.  
  4687.  
  4688. Paste Selection Behind also preserves indentation. And so does
  4689. Drag and Drop, if the drag starts within EnterAct.
  4690.  
  4691. §    Drag and Drop for text
  4692. Dragging and dropping text is almost entirely standard in EnterAct,
  4693. and all you need to know about D&D is:
  4694.     • you drag text around by making a selection and then dragging
  4695.     (mouse-down on the selected text, then move the mouse with
  4696.     the button still down). As you drag about, a cursor will move
  4697.     with you showing exactly where the drop will take place if
  4698.     you let go of the mouse button
  4699.     • when you drag text within its source window, you are "moving"
  4700.     it, ie it will be deleted from its original location and inserted
  4701.     where you see the cursor flashing as you move about
  4702.     • to duplicate rather than move the text when you're still in the
  4703.     source window, hold down the <option> key as you start or end
  4704.     the drag
  4705.     • if you drag the text to a different window, the original text
  4706.     in your source window will not be affected ever
  4707.     • I lied, if you drag the text to the trash it will be deleted from
  4708.     your source window
  4709.     • if the D&D starts and ends within EnterAct, your indentation
  4710.     will be preserved
  4711.     • to cancel a drag, release the mouse when it's over the top part
  4712.     of the title bar or over the original selection when you're still in
  4713.     the source window, or over the title or scroll bars when you're over
  4714.     some other window; or for that matter let go when you're in the 
  4715.     menu bar at top of the screen
  4716.     • all Drag & Drops of text (even to the trash) are undoable.
  4717.  
  4718. As you drag about in the source window, you can persuade EnterAct
  4719. to scroll the text in the window by moving your mouse to the edges
  4720. of the window (scroll bars, and small margins at the top and left).
  4721. Inactive windows, in accordance with Apple's guidelines, do not
  4722. scroll the text automatically as you drag around in them.
  4723.  
  4724. Unless or course you want them to: in which case open the Options
  4725. dialog, click on the "Edit" pane, and check the box called "Autoscroll
  4726. inactive windows when dragging". This applies only if the drag starts
  4727. in EnterAct. DON"T get too used to this, or you might forget that
  4728. it violates the guidelines! Cancelling a drag is slightly harder due to
  4729. autoscrolling, but the drag does cancel if you let go of the mouse
  4730. while autoscrolling.
  4731.     
  4732.  
  4733. §    Code templates
  4734. Save those fingers. All templates are stored in the text file
  4735. "EnterAct Code Templates", which is very easy to modify (please
  4736. take a look at it). Add this file to the folder where you keep
  4737. EnterAct, at the same level. If you save changes to your "EnterAct
  4738. Code Templates" file using EnterAct, your new templates are
  4739. instantly available (no need to quit and restart).
  4740.  
  4741. To use a template, you type its name and press <command><return>.
  4742. And <command><return> will also advance you to the next logical
  4743. insertion point in your template (or in any code for that matter).
  4744. Templates don't have to contain code, and template names can
  4745. contain any non-blank characters, not just letters and numbers.
  4746.  
  4747. To force <command><return> advancing to stop at a particular point,
  4748. put an '@' sign in the template. Then <command><return> will stop
  4749. at the '@' sign and select it. There's an example just below.
  4750. (For templates that contain C/C++/Java code, <command><return> will
  4751. advance to almost all logical insertion points, with no need for
  4752. '@' signs in the template. But feel free to put them in anywhere.) 
  4753.  
  4754. Keep all your entries flush-left, and EnterAct will adjust your
  4755. indentation when pasting your template in. Just open up a new line
  4756. and tab in to the right position before typing the entry name and
  4757. pressing <command><return>.
  4758.  
  4759. Here are two templates, from the "EnterAct Code Templates" file:
  4760. ____
  4761.  
  4762. ENTRY
  4763. for
  4764. for (; ; )
  4765.     {
  4766.     
  4767.     }
  4768.  
  4769. END
  4770. ENTRY
  4771. i
  4772. #include "@.h"
  4773.  
  4774. END
  4775.  
  4776. ____
  4777. Each entry begins with "ENTRY" on a separate line, followed by the
  4778. name of the entry on a separate line, then the body of the template
  4779. definition, and finally "END" on a separate line. To use the "for"
  4780. template, you would type "for" and then press <command><return>.
  4781. That would paste in the body of the template, and advance your
  4782. insertion point to just before the first ';'. Every subsequent press
  4783. of <command><return> would advance you to the next logical insertion
  4784. point in the template. In the "i" (for "include") template, typing "i"
  4785. plus <command><return> would replace the "i" with
  4786. ____
  4787. #include "@.h" [plus a new line]
  4788. ____
  4789. and select the '@' sign so you could type in a file name.
  4790.  
  4791. You can use templates to hold arbitrary chunks of text. For example,
  4792. if you find yourself typing "if (theErr == noErr) {}" a lot, you could
  4793. reduce this to "e" plus <command><return> with a template
  4794. entry such as
  4795. ____
  4796. ENTRY
  4797. e
  4798. if (theErr == noErr)
  4799.     {
  4800.     
  4801.     }
  4802.  
  4803. END
  4804. ____
  4805.  
  4806. Tip: add "EnterAct Code Templates" to your "Locations" menu so you
  4807. can change your templates on the fly. Remember, when you change
  4808. your "EnterAct Code Templates" with EnterAct the updated templates
  4809. are instantly available.
  4810.  
  4811. hAWK command lines are handled specially: if your template name
  4812. expands into a hAWK command line, it will all be selected, and if
  4813. you press <command><return> a second time, Enteract will run the
  4814. specified hAWK program. Here's a sample hAWK command line entry
  4815. from the code templates file:
  4816. ____
  4817. ENTRY
  4818. echo
  4819. hAWK -f$EchoFullPathNames -- MFS
  4820.  
  4821. END
  4822. ____
  4823. EnterAct treats any selection beginning with "hAWK" as a hAWK
  4824. command line. If you type "echo" in a text window and then press
  4825. <command><return>, then "hAWK -f$EchoFullPathNames -- MFS"
  4826. will be pasted in as usual for a code template, but because it's
  4827. a hAWK template, the entire line will be selected. The special
  4828. symbol "MFS" stands for all files in your multi-file selection
  4829. in your current project (the files with bullets on their left in the
  4830. project window). So to run this program for real you should first
  4831. select some file for multi-file operations in a project (see the
  4832. Search chapter) and then type "echo<command><return><command>
  4833. <return>". You will end up with a list of full path names for your
  4834. selected files in the "stdout" window.
  4835.  
  4836. §    Selection: front, non–front
  4837. EnterAct uses your chosen highlight color to show the selection in a
  4838. text or project window when it is in front. In text windows that are
  4839. not in front, the selection is framed with a black box. With Drag and
  4840. Drop enabled (which it is by default), you can drag any selection
  4841. around, or make a copy within the same window by holding down the
  4842. <option> key as you drag.
  4843.  
  4844. The selection in the second-front text window is not shown
  4845. differently from other non-front windows, but this is the selection
  4846. that will be affected by the Paste Selection Behind command
  4847. (described in the next section), and it also shows where your search
  4848. will start from when the Find dialog is in front of your text window.
  4849.  
  4850. §    Paste Selection Behind
  4851. Paste Selection Behind does the following three actions in one : Copy
  4852. what is selected in the front window; switch to the window just behind
  4853. it; and Paste the copy in over the selection in that window. You’ll
  4854. see your selection in the next–to–front window just beforehand, as
  4855. described above. If you can’t see what is selected in the next–to–front
  4856. window, you can either trust to memory (it’s undoable) or do a “manual”
  4857. Copy, switch windows, Paste.
  4858.  
  4859. Paste Selection Behind is especially handy when switching back and
  4860. forth between your working text window and a lookup window, but it can
  4861. be used with any two text windows.
  4862.  
  4863. Your indentation will be preserved with Paste Selection Behind under
  4864. the same circumstances that apply to a Paste (see “Paste preserves
  4865. indentation” above).
  4866.  
  4867. If you want to undo a Paste Selection Behind but have switched to a
  4868. different window, bring the two windows involved in the Paste Selection
  4869. Behind to the front alternately until Undo becomes enabled. The two
  4870. windows involved are the one you pasted into, and the one you copied
  4871. from.
  4872.  
  4873. (before Paste Selection Behind: I typed "PutResInfo", but nothing showed
  4874. up in the AutoLook window so I pressed <enter> to produce the
  4875. "••PutResInfo" lookup window--WriteResInfo is what I wanted)
  4876.  
  4877.  
  4878.  
  4879.  
  4880.  
  4881.  
  4882.  
  4883.  
  4884.  
  4885.  
  4886.  
  4887.  
  4888.  
  4889.  
  4890.  
  4891.  
  4892.  
  4893. (after Paste Selection Behind)
  4894.  
  4895.  
  4896.  
  4897.  
  4898.  
  4899.  
  4900.  
  4901.  
  4902.  
  4903.  
  4904.  
  4905.  
  4906.  
  4907.  
  4908.  
  4909.  
  4910.  
  4911. §    Font, font size, tabs
  4912. Sizes for your font are restricted to sizes that are actually installed
  4913. in your system. The default font for text windows in EnterAct is Monaco
  4914. 9, with 4 spaces per tab.
  4915.  
  4916. You can also change the font for the project window. The default here
  4917. is also Monaco 9.
  4918.  
  4919. For projects only, holding down the <Option> key while changing
  4920. the font or size will give you a bold style.
  4921.  
  4922. Tabs in EnterAct are of the relative sort, meaning that when you press
  4923. <Tab> your insertion point advances to the next tab stop. Tab stops
  4924. are placed a fixed number of spaces apart, and you can change this
  4925. number with the Tabs dialog. Note that if you change the font it may
  4926. throw off your nicely–aligned code, so it’s best to pick one font for
  4927. code at the beginning of your programming career and stick with it.
  4928.  
  4929.  
  4930.  
  4931.  
  4932.  
  4933.  
  4934.  
  4935.  
  4936.  
  4937.  
  4938.  
  4939. §    Shift Left / Right
  4940. Shift Left and Shift Right will shift one or more entire lines left
  4941. or right by a tab stop, allowing you to repair or alter the relative
  4942. indentation of your code or text. For simplicity, you should select
  4943. one or more entire lines before calling these commands. They are
  4944. undoable.
  4945.  
  4946.  
  4947.  
  4948.  
  4949.  
  4950.  
  4951.  
  4952.  
  4953.  
  4954.  
  4955.  
  4956. (the effect of Shift Left on the above selection)
  4957.  
  4958.  
  4959.  
  4960.  
  4961.  
  4962.  
  4963.  
  4964.  
  4965.  
  4966.  
  4967.  
  4968.  
  4969.  
  4970. §    Reformat Selection
  4971. Reformat Selection will rebreak the lines in your selection, but the
  4972. result may not always be an improvement. It is designed to work with
  4973. multiple paragraphs, provided you don’t indent the beginning of the
  4974. first line, and that you separate paragraphs with a blank line.
  4975.  
  4976.  
  4977.  
  4978.  
  4979.  
  4980.  
  4981.  
  4982.  
  4983.  
  4984.  
  4985.  
  4986.  
  4987.  
  4988. (the above after Reformat Selection, with the default settings)
  4989.  
  4990.  
  4991.  
  4992.  
  4993.  
  4994.  
  4995.  
  4996.  
  4997.  
  4998.  
  4999.  
  5000.  
  5001.  
  5002. Reformat Selection doesn’t work well on C code, although it may on
  5003. occasion help to tidy up a complicated “if” statement. It works best
  5004. with one or more paragraphs of text, either an entire comment or part
  5005. of a comment, or paragraphs in a text document.
  5006.  
  5007. Since Reformat Selection is undoable there’s no harm in trying it. The
  5008. maximum selection that can be reformatted at one time is roughly the
  5009. standard Text Edit limit, 32,000 or so characters.
  5010.  
  5011. The specific reformatting that Reformat Selection does is governed by
  5012. the two "Reformat" options in the Options dialog. The default action is
  5013. to rebreak lines with a “ragged right” format and a maximum line
  5014. length of 74 characters, a nice width for printing Monaco 9. In the
  5015. Options dialog (near the bottom) you can alter the maximum number of
  5016. characters per line, and also select a “full justification” look if you
  5017. want to knock people over with your comments. The maximum number
  5018. of characters per line is restricted to a range of 30 to 150.
  5019.  
  5020. §    Syntax coloring
  5021. Color can be applied to comments, strings, and constants inside
  5022. ticks -- if you don’t like the default colors, there are a few
  5023. commands to change them, under the Edit menu.
  5024.  
  5025. This is a simple implementation of coloring. The goal here was to
  5026. color only those things that might usefully be colored, things that
  5027. don’t immediately catch the eye and yet are of some importance.
  5028. Keywords are not colored; if they don’t immediately catch your eye
  5029. yet, just be patient, with a bit more programming under your belt they
  5030. will.
  5031.  
  5032. Syntax coloring might improve with future versions, but one thing
  5033. you can say about EnterAct’s coloring: it doesn't flicker!
  5034.  
  5035. If you grow bored with merely colored comments, try out the
  5036. "Comment options..." command under the Edit menu.
  5037.  
  5038. §    Graphic nesting display
  5039. Hold down the <Option> AND <Command> keys with a source file
  5040. frontmost and vertical lines will appear showing the scope of
  5041. each statement block (ie anything inside {} curly braces). It’s
  5042. OK to scroll with these keys down, but you should release them
  5043. before further editing (I think).
  5044.  
  5045. §    Arrow keys for moving around
  5046. The up down left right arrow keys will move your cursor by one
  5047. character or line. If you hold down the <Option> or <Command> key an
  5048. arrow key will take you all the way in the appropriate direction.
  5049. <command><up arrow> and <command><down arrow> are especially
  5050. useful for taking you to the top or bottom of your document.
  5051.  
  5052.  
  5053. §    Illustrating your text
  5054. As you can see from this manual, there is a way to put PICT's in a
  5055. text document. You can place dialog and screen snapshots,
  5056. structure mockups, flowcharts, state machines, in short, any old
  5057. PICT, into your spec, design, and test documents, even into your
  5058. code files (EnterAct’s style of illustration goes unnoticed by
  5059. compilers, PROVIDED you place the picture inside a /*comment*/).
  5060.  
  5061. EnterAct's illustration capabilities are two in number: paste,
  5062. by dragging a PICT in from another application; and delete, by
  5063. "swiping" a PICT. Both of these are undoable.
  5064.  
  5065. To Paste a PICT into a document: drag & drop it from another
  5066. application (such as the Scrapbook). Note EnterAct cannot serve
  5067. as the source for your PICT, only as the destination.
  5068.  
  5069. To delete a PICT: "swipe" a small text selection within the PICT,
  5070. to produce a dialog that asks if you want to delete the PICT: click OK.
  5071.  
  5072.  
  5073.  
  5074.  
  5075.  
  5076. "Swipe"? That means do a fast mouse-down drag mouse-up. Beat
  5077. your double-click time while selecting a blank line or three. Or if
  5078. you prefer something more elegant, you can click on one line within
  5079. the PICT and then <shift>click at your leisure on a different line.
  5080.  
  5081. Pasting and deletion of PICTs are undoable operations. For a Paste,
  5082. the undo item will refer to a Drag&Drop Paste, and for a delete of
  5083. a PICT the undo menu item refers to a "Clear".
  5084.  
  5085. PICTs are not recorded in your activity log. If you really need persistent
  5086. undo for PICTs, please contact your author at the address at top of this
  5087. manual. Be persuasive, because it wouldn't be easy.
  5088.  
  5089. The position of each PICT is marked in the text by a
  5090. <return><option-space> pair, and "blank" space is opened up for
  5091. the PICT with a series of <return>s. Pasting or deleting a PICT makes
  5092. a permanent change to the resource fork of your document (where the
  5093. PICTs are kept) but the inserted text for the PICT position is not
  5094. saved for you. To avoid surprises, Save after every Paste or delete
  5095. of a picture.
  5096.  
  5097. You can Paste up to 400 PICTs into one EnterAct document.
  5098.  
  5099. PICTs can also be manually inserted by using a combination of a
  5100. resource editor and text editing, as explained next. However, using
  5101. EnterAct's Paste is far more convenient.
  5102.  
  5103. (PLEASE NOTE the following "manual" approach is no longer practical,
  5104. and is preserved here for information purposes only. This is because
  5105. EnterAct now always renumbers your PICTs when you use the above
  5106. paste/delete approach, and uses the sequence 1,000, 1,001...1,400
  5107. without any gaps. This is "Teach Text" compatible, but makes any
  5108. manual insertion of PICTs impossibly tedious. You win some, you
  5109. lose some.)
  5110.  
  5111. Illustrations come in two parts: PICT resources, placed in the resource
  5112. fork of your document using ResEdit or equivalent; and “picture
  5113. markers” in the text of your document, each consisting of a <Return>
  5114. followed immediately by an <Option><space>.
  5115.  
  5116. If you have more than one illustration in a document, the PICT’s should
  5117. be given ID numbers in the same sequence as they are to appear in your
  5118. document. The numbers should be between 128 and 32,767, and if you
  5119. anticipate coming back later to insert new pictures between old ones
  5120. you should space the numbers out a bit, using for example the sequence
  5121. 1,000, 1,100, 1,200.... All PICT’s should be made purgeable, as
  5122. EnterAct does not insist on keeping the PICT’s in memory. In ResEdit,
  5123. you can mark the PICT as purgeable at the same time as you set the ID
  5124. number, using “Get Info...” with the PICT selected.
  5125.  
  5126. For each PICT you wish displayed, you’ll need a <Return>  
  5127. <Option><space> pair at the position where you wish the illustration
  5128. to appear. The simplest approach is to first use ResEdit to install
  5129. your PICT’s in the document, then open the document using EnterAct and
  5130. insert an <Option><space> at the beginning of the line where you want
  5131. the first picture to appear. As you type the <Option><space>, the
  5132. picture will begin to appear—you should then type enough <Return>’s
  5133. to open up blank lines for the picture to occupy, so that it doesn’t
  5134. overlap any following text (however, you may certainly overlap picture
  5135. and text if you want). If you need to see the picture fully redrawn
  5136. while doing this, click in the up or down arrow of the vertical scroll
  5137. bar. Repeat for any following pictures.
  5138.  
  5139. To sum up, the PICT’s in the resource fork of your document should have
  5140. ID numbers that are in the same order as you want them displayed; for
  5141. each picture there should be a <Return> <Option><space> followed by
  5142. enough blank lines to make room for the picture.
  5143.  
  5144. To insert a PICT between two existing PICT’s, give it an ID number
  5145. between the numbers for the flanking PICT’s when you paste it in with
  5146. ResEdit, and put the “picture marker” of course between the flanking
  5147. markers.
  5148.  
  5149. Note that if you add PICTs using a resource editor and then later use
  5150. EnterAct to Paste a PICT into the same document, your PICTs will
  5151. be renumbered automatically using the sequence 1,001, 1,001,
  5152. 1,002... up to 1,400 without gaps.
  5153.  
  5154. If your pictures end up displayed in the wrong order, you can be sure
  5155. that their ID numbers are not in the correct order. A missing picture
  5156. means that either the PICT or the <Return> <Option><space> for it is
  5157. missing. A picture can be moved around between two flanking pictures
  5158. just by cutting and pasting the picture marker, but to change the order
  5159. of pictures you will have to change the PICT ID numbers to the sequence
  5160. you want. Excess PICT’s won’t be displayed until you enter a picture
  5161. marker, and excess markers don’t hurt, but may be triggered
  5162. unexpectedly if you add a PICT at the end of your file.
  5163.  
  5164. A file with two PICT illustrations that have been pasted in
  5165. using ResEdit:
  5166.  
  5167.  
  5168.  
  5169.  
  5170.  
  5171.  
  5172.  
  5173.  
  5174.  
  5175.  
  5176.  
  5177.  
  5178.  
  5179.  
  5180. The "Activities" PICT in "EnterAct Log": the small black rectangle is
  5181. the <Option><space> that marks the picture insert position (shown
  5182. selected). Several <Return>'s follow, to open up enough room for the
  5183. picture.
  5184.  
  5185.  
  5186.  
  5187.  
  5188.  
  5189.  
  5190.  
  5191.  
  5192.  
  5193.  
  5194.  
  5195.  
  5196.  
  5197.  
  5198.  
  5199.  
  5200.  
  5201. For a whopping big example, examine this document and its resources.
  5202.  
  5203.  
  5204. -    -    -    -    -    -    -    -    -    -    -    -
  5205. Balance
  5206. -    -    -    -    -    -    -    -    -    -    -    -
  5207. NOTE you can also Balance a delimiter by double-clicking on it.
  5208.  
  5209. §    Checks everything
  5210. ...except those angular brackets that you find only in
  5211. ____
  5212.         #include <SystemHeader.h>.
  5213. ____
  5214. The full list is (), [], {}, /* */, " ", and ' '.
  5215.  
  5216. Balance will also detect nested comments and any single
  5217. improperly–formed comment start or end. Two improper comment
  5218. delimiters in a row (improper start followed by improper end, or vice
  5219. versa) will not be detected, but that’s a one–in–a–million case that
  5220. you’ll probably never see.
  5221.  
  5222. Because Balance detects nested comments, it will signal an error if
  5223. you use a comment start or end within a comment (nested comment starts
  5224. are excepted if you deselect the “Detect nested comment starts” option
  5225. in the Options dialog)—see “Nested and bad comments” below. 
  5226.  
  5227. For strings in double quotes " ", the line continuation character '\'
  5228. must be the last character on the line if the string is continued to
  5229. the next line:
  5230. ____
  5231.     "This string is \<Return>
  5232.     properly continued."
  5233.     "This string will trigger<Return>
  5234.     a Balance error."
  5235.     "So will \<space><Return>
  5236.     this string, due to the space before Return."
  5237. ____
  5238. Balance will behave in different ways depending on where you are in
  5239. the code. To Balance an entire file, select an insertion point at the
  5240. very top of the file (<Option><up arrow> will take you there). To
  5241. Balance a specific delimiter, either click just to the left of it or
  5242. select the delimiter (note for comment starts and ends this means both
  5243. characters). 
  5244.  
  5245. Given an insertion point, Balance will first look to the immediate
  5246. right for a delimiter that wants balancing, and then to the immediate
  5247. left. When several delimiters are side by side, you can avoid having
  5248. to remember this by just selecting the delimiter you wish balanced.
  5249. Clicking between the characters of a comment start or end also counts
  5250. as a “hint” to find the other end. 
  5251.  
  5252. If your range of characters selected doesn’t consist of just a single
  5253. delimiter, or if your insertion point is not right next to a delimiter,
  5254. then Balance will try to find the smallest enclosing pair of
  5255. delimiters. Your selection range will expand to the next enclosing pair
  5256. as you repeat the Balance command.
  5257.  
  5258.  
  5259. §    Shows the error location
  5260. Any unmatched or mismatched delimiter will be selected and shown. In
  5261. the case of mismatched delimiters, you can switch between the two
  5262. delimiters by selecting Balance again. If the delimiter is an “orphan”,
  5263. the second Balance will just produce a beep, since there’s no other
  5264. end to show.
  5265.  
  5266.  
  5267.  
  5268.  
  5269.  
  5270.  
  5271.  
  5272.  
  5273.  
  5274.  
  5275.  
  5276.  
  5277.  
  5278. (if there’s a mismatch, a second Balance will show the other end)
  5279.  
  5280.  
  5281.  
  5282.  
  5283.  
  5284.  
  5285.  
  5286.  
  5287.  
  5288.  
  5289.  
  5290.  
  5291.  
  5292. §    Balancing a file
  5293. Given an insertion point at the top of a file, Balance will balance
  5294. the entire file. If you hear a beep and the cursor does not move from
  5295. the top of the file, that means the entire file is balanced. Either
  5296. Go Top or <Option><up arrow> will take you to the top of a file.
  5297.  
  5298. Balancing a file by starting from the top will always work correctly.
  5299. You can also Balance a file by starting at the very bottom, but this
  5300. may not work properly if the file contains any assembly–language
  5301. sections (see “The asm problem” at the end of this chapter).
  5302.  
  5303.  
  5304. §    Balancing a specific delimiter
  5305. Balance looks for a “hint” from you, as indicated by your insertion
  5306. point or selection, before going ahead. As mentioned above, you can
  5307. Balance one specific delimiter by selecting it just before the balance,
  5308. or by selecting an insertion point just to the left of it. If the
  5309. delimiter is not next to another delimiter, you can click on either
  5310. side of it. With comments and strings it is best to start the Balance
  5311. off with a “hint”, that is, select one end of the comment or string
  5312. or click next to one end, since if you start in the middle of a comment
  5313. or string the text will be checked as strictly as possible, without
  5314. allowance for it being within a comment or string.
  5315.  
  5316.  
  5317.  
  5318.  
  5319.  
  5320.  
  5321.  
  5322.  
  5323.  
  5324. (Balance will take the selected ')' as a hint)
  5325.  
  5326.  
  5327.  
  5328.  
  5329.  
  5330.  
  5331.  
  5332.  
  5333.  
  5334.  
  5335.  
  5336. §    Nested and bad comments
  5337. Balance will detect all nested comments, and any comment that has one
  5338. end missing. In the case of a comment with one end missing , you will
  5339. be shown a “good” end in the vicinity of the bad one, and you’ll have
  5340. to deduce on your own where the other end should be. Comment errors
  5341. can sometimes be subtle and difficult to see, such as a space between
  5342. the '*' and the '/'.
  5343.  
  5344. (The first comment shown here is not ended properly. Balance detects
  5345. the start of the second comment as an attempt to nest comments, and
  5346. shows it as an error.)
  5347.  
  5348.  
  5349.  
  5350.  
  5351.  
  5352.  
  5353.  
  5354. (An immediate second Balance will show that the lower comment
  5355. is correct, implying that the error was in the comment just above.)
  5356.  
  5357.  
  5358.  
  5359.  
  5360.  
  5361.  
  5362.  
  5363.  
  5364. If you leave the “Detect nested comment starts” check box checked in
  5365. the Options dialog, then any files in your EnterAct project are
  5366. guaranteed to be free of these comment errors after a successful
  5367. Update Dictionary, since the dictionary–builder checks comments
  5368. thoroughly.
  5369.  
  5370. The one price to be paid for EnterAct’s improved comment checking is
  5371. that you should not use a comment start or end within a comment. Such
  5372. things as
  5373.     /*.../*...*/
  5374. and
  5375.     /*...*/...*/
  5376. will be treated as errors, both by the Balance command and by the
  5377. dictionary–builder. If you do need to use a comment start or end within
  5378. a comment, the general cure is to place some character between the star
  5379. and the slash. A space will do, or you could be pedantic and place each
  5380. character in separate single quotes, for example instead of /* use / *
  5381. or '/''*'.
  5382.  
  5383. Well, OK—some of you deliberately double up your comment starts to save
  5384. on typing. If you do this, select the Options command under the Edit
  5385. menu and uncheck the “Detect nested comment starts” check box. This
  5386. affects the dictionary builder also.
  5387.  
  5388.  
  5389.  
  5390.  
  5391.  
  5392.  
  5393.  
  5394.  
  5395.  
  5396.  
  5397. §    Starting in the middle
  5398. If your selection doesn’t indicate a hint, Balance first looks
  5399. backwards in your file for a delimiter; when it finds one, it then
  5400. looks forwards for another delimiter, hoping to match them up. Of
  5401. course, if you supply an opening delimiter as a “hint”, or start from
  5402. the top of the file, Balance will proceed in the forward direction
  5403. immediately.
  5404.  
  5405. On rare occasions you may wish to balance the contents of a comment
  5406. or string as though it were code, and not just text. To do this, click
  5407. or select a range of characters within the comment or string, away from
  5408. either end. Balance will then check all delimiters as it works
  5409. outwards, until it encounters one end of the comment or string and
  5410. “realizes” that it has been fooled. 
  5411.  
  5412. By the way, EnterAct also accepts “C++” style comments, as in
  5413. ____
  5414.     //comment beginning with two slashes, to end of line
  5415. ____
  5416. but only to the extent of skipping over the contents when balancing.
  5417. If you start the Balance within this sort of comment it may just
  5418. beep at you. 
  5419.  
  5420. Before Balancing:
  5421.  
  5422.  
  5423.  
  5424.  
  5425.  
  5426.  
  5427.  
  5428.  
  5429.  
  5430.  
  5431.  
  5432. After the first Balance:
  5433.  
  5434.  
  5435.  
  5436.  
  5437.  
  5438.  
  5439.  
  5440.  
  5441.  
  5442.  
  5443.  
  5444. After a second Balance:
  5445.  
  5446.  
  5447.  
  5448.  
  5449.  
  5450.  
  5451.  
  5452.  
  5453.  
  5454.  
  5455.  
  5456.  
  5457. §    The asm problem
  5458. If Balance runs into an “asm {...}” construction while looking
  5459. backwards through your code, it just plain won’t know that it’s inside
  5460. an asm. Any error you’re shown in this one circumstance is not to be
  5461. trusted, since it will almost certainly be due to a delimiter inside
  5462. an assembly–language comment (they start with a semicolon). 
  5463.  
  5464. When you balance a file from the top, all asm constructions will be
  5465. handled properly. The dictionary–builder, by the way, also handles
  5466. asm’s properly. Be warned that in other cases if you ask Balance to
  5467. run backwards through a block of assembly language it will hiccup if
  5468. it runs into a delimiter within an assembly–language comment. This is
  5469. a bug, but I haven’t found a cure that wouldn’t slow balancing down
  5470. to a crawl. 
  5471.  
  5472. Because of this problem it is best to always balance an entire file
  5473. by starting from the top rather than from the bottom, unless you’re
  5474. sure that the file contains no assembly language.
  5475.  
  5476. To Balance an assembly–language block, or a function containing
  5477. assembly language, select or click next to the opening curly brace '{'
  5478. at the top rather than the closing curly brace.
  5479.  
  5480. Otherwise, this will only be a problem if you’re balancing inside a
  5481. function that contains a block of assembly language. Then, you should
  5482. select opening delimiters rather than closing delimiters before
  5483. balancing. 
  5484.  
  5485.  
  5486. -    -    -    -    -    -    -    -    -    -    -    -
  5487. Search
  5488. -    -    -    -    -    -    -    -    -    -    -    -
  5489.  
  5490.  
  5491.  
  5492.  
  5493.  
  5494.  
  5495.  
  5496.  
  5497.  
  5498.  
  5499.  
  5500. (both Find and Replace strings are limited to 255 characters)
  5501.  
  5502. §    Introduction
  5503. Single and multi–file searches in EnterAct are controlled by a modeless
  5504. Find dialog. The one important novelty is that you fine–tune your
  5505. multi–file selection by holding down the <Option> key and dragging over
  5506. the files in the project window (bullets • appear beside each file
  5507. included in the search). Your multi-file selection can also be used
  5508. to remove files from a project, or used by a hAWK program as a list
  5509. of files to take input from.
  5510.  
  5511. Replace, Replace and Find Again, and Replace All are all undoable.
  5512. The commands Find, Find Again, and Enter Selection all function when
  5513. the project window is in front, and the “find” commands also function
  5514. when the project window is just behind the Find dialog. Find commands
  5515. will search the currently active pane, useful if you are trying to spot
  5516. one file in a long list, or pick out files with similar names. Enter
  5517. Selection will enter the currently-selected file name in the Find
  5518. dialog.
  5519.  
  5520.  
  5521. §    Find is modeless
  5522. This requires a few minor adjustments in the way you search. 
  5523. There is no Cancel button in the Find dialog box—it has a Close box
  5524. instead. 
  5525.  
  5526. While the Find dialog is the front window, search commands that deal
  5527. with single files will apply to the window just beneath the Find
  5528. dialog. Replace All is excepted because it can cause multiple changes,
  5529. so to use this command you must have the text window in front.
  5530.  
  5531. Find and Find Again also function if the Find dialog is in front of the
  5532. project window, searching the current pane as though it were a text
  5533. list of file names (actually, that’s what it is…).
  5534.  
  5535. The “Find” button is the equivalent of the Find Again command. When
  5536. you click the Find button or select Find Again, the window just beneath
  5537. the Find dialog will be brought to the front, and the next instance
  5538. of your find string shown. The Find dialog will stay on–screen, moving
  5539. just behind the window being searched, so to find again you can if you
  5540. wish leave your mouse stationed over the Find button and double–click
  5541. (not a true double–click, the first click brings the Find dialog to
  5542. the front, and the second does the Find Again).
  5543.  
  5544. Buttons for multi–file searching are incorporated directly in the Find
  5545. dialog (more on this in “Multi-file searches” below). To modify your
  5546. multi–file search selection of files, hold down the <Option> key and
  5547. drag over the file names in the project window. You’ll see the
  5548. “eyeball” cursor while doing this.
  5549.  
  5550.  
  5551.  
  5552.  
  5553.  
  5554.  
  5555.  
  5556.  
  5557.  
  5558.  
  5559.  
  5560.  
  5561.  
  5562.  
  5563.  
  5564.  
  5565.  
  5566. §    Find options
  5567. Select “Match Words” if  you don’t wish to match a longer string that
  5568. contains your find string in a form that makes a different word. For
  5569. example, the string “Open” will also match “Opening”, “Opened” etc
  5570. unless you select the “Match Words” option in the Find dialog.
  5571.  
  5572. A special case: if your string begins or ends with punctuation, such
  5573. as “->structMember” then leave “Match Words” unselected.
  5574.  
  5575. “Wrap Around” will continue your search from the beginning of your
  5576. document if the next Find runs off the bottom end of it. 
  5577.  
  5578. This also affects the Replace commands: to Replace All instances in
  5579. a file, it’s simplest to select an insertion point at the top of the
  5580. file beforehand; to Replace All instances below a certain point, click
  5581. just before the position where you want the replacing to start, and
  5582. leave “Wrap Around” deselected.
  5583.  
  5584. “Ignore Case” treats upper and lower–case letters as the same.
  5585.  
  5586. §    Batch Find options
  5587. If you click the "Batch" check box, your multi-file search will be
  5588. done all at once, and the results presented in a text window
  5589. (file name, line number, and the full line where found). To view
  5590. a particular found instance in the original file, click on the result
  5591. line and use "Go to...".
  5592.  
  5593. For Batch finds, if you select "List markers" then the line that lists
  5594. a particular location will include the containing function name.
  5595. Here's an example result (results appear in the stdout window):
  5596. ____
  5597. Batch find results for: «nextName»
  5598. --------------------------------------------
  5599. «CEDAR_AutoLook.c»  3513 |ResolveOneLink| Boolean ResolveOneLink(StringPtr t1, short nextName, Handle *hTextP, long *primaryLinkP)
  5600. «CEDAR_AutoLook.c»  3524 |ResolveOneLink|         // Note nameLink0 is set only if nextName == 0.
  5601. «CEDAR_AutoLook.c»  3841 |GetSomeTypeNameForMember| /* typeLink1 is the index of a type name, nextName is sNameChain index
  5602. «CEDAR_AutoLook.c»  3843 |GetSomeTypeNameForMember| for nextName (and if nextName is 0 set nameLink0), return TRUE;
  5603. ____
  5604. Once again, to jump to a particular instance, click on the line that
  5605. contains the file location and use "Go to...".
  5606.  
  5607. Please see "§    Skip '-' : excluding files from a search" below if you wish
  5608. to skip certain files easily while searching or carrying out some
  5609. other multi-file operation.
  5610.  
  5611. §    Dual Batch Find
  5612. Translated into English, the dialog that appears when you click the
  5613. Dual Batch Find button in the Find dialog lets you do "Find two
  5614. strings wihin a certain number of lines or characters of each
  5615. other". This is a multi-file operation, that is it looks in files
  5616. that you've bulleted for multi-file searches, and it's a Batch
  5617. operation in that it presents its result in the stdout window.
  5618.  
  5619. To find the two strings on the same line, enter a zero for the
  5620. number of lines. Zero characters means the two strings must
  5621. be found right together with no characters in between.
  5622.  
  5623. Dual Batch Find is a sort of mini-grep for dummies (like me).
  5624. hAWK can perform full grep searches if you need the extra power
  5625. (but in practice I've found that setting up grep searches is too
  5626. error-prone for casual use).
  5627.  
  5628. Both strings that you enter in the Dual Batch Find dialog obey
  5629. the "Match Words" and "Ignore Case" options that you select
  5630. in the main Find dialog.
  5631.  
  5632. §    <Tab> and <Return>
  5633. A plain <Tab> will jump your cursor from one edit field to the other,
  5634. and a plain <Return> is the equivalent of the “Find” button. To enter
  5635. a <Tab> or <Return> in either the find or the replace text, hold down
  5636. the <Command> key while typing the character.
  5637.  
  5638.  
  5639. §    Find again
  5640. This menu command is the equivalent of the “Find” button in the Find
  5641. dialog, and finds the next instance of your find string in accordance
  5642. with your Find options (see above). Find Again searches the front
  5643. window, or, if the Find dialog is in front, the window just behind the
  5644. Find dialog.
  5645.  
  5646. Find Again also works with the project window, allowing you to search
  5647. for part of a file name in a long list of files. It searches the active
  5648. pane only (the one with filled-in scroll bars).
  5649.  
  5650.  
  5651. §    Enter selection
  5652. Enter Selection will replace your current find string with whatever
  5653. text you have selected. It works with any text window including lookup
  5654. windows, and also the project window (in case you wish to search for
  5655. a file name). If your Find dialog is on–screen, you will see the new
  5656. find string in the dialog.
  5657.  
  5658.  
  5659. §    Recent finds are remembered
  5660. Your most–recent find strings will be stored in the popup “Find:” menu
  5661. at top–left of the Find dialog. Selecting an item from the popup will
  5662. copy it to your find string box.
  5663.  
  5664. Two minor limitations apply: find strings containing <Return>s or more
  5665. than 48 characters will not be remembered by the popup menu.
  5666.  
  5667.  
  5668.  
  5669.  
  5670.  
  5671.  
  5672.  
  5673.  
  5674.  
  5675.  
  5676.  
  5677.  
  5678.  
  5679.  
  5680.  
  5681.  
  5682.  
  5683.  
  5684.  
  5685.  
  5686.  
  5687.  
  5688.  
  5689.  
  5690. §    Replace
  5691. Replace can be thought of as a Paste for short strings (up to 255
  5692. characters). The replacement text is taken from the replace string in
  5693. the Find dialog. No checking is done to see if the selection that will
  5694. be replaced corresponds to your find string, so the replacement string
  5695. can in effect be used as a second (small) clipboard. To set up a choice
  5696. between two “Paste” alternatives, enter one selection into the
  5697. replacement string in the Find dialog, and then Copy the other
  5698. selection. Then Paste or Replace in your document as appropriate.
  5699.  
  5700. If the Find dialog is in front, Replace will affect the window just
  5701. behind the Find dialog.
  5702.  
  5703. Replace is undoable provided the window in which the Replace was done
  5704. is in front, and provided you don’t perform some other undoable action
  5705. before undoing.
  5706.  
  5707.  
  5708. §    Replace and Find Again
  5709. This command is the exact equivalent of Replace followed by Find Again,
  5710. and is undoable.
  5711.  
  5712.  
  5713. §    Replace All
  5714. Unlike other search commands, Replace All cannot be called when the
  5715. Find dialog is in front—you must specifically bring frontmost the
  5716. window in which you wish to use Replace All. This small awkwardness
  5717. is an attempt to remind you that Replace All is the one editing command
  5718. that can make a real mess of your document. However, it is undoable—as
  5719. with other undoable operations, you need only have the correct window
  5720. in front before undoing.
  5721.  
  5722. If you have selected the “Wrap Around” option in the Find dialog,
  5723. Replace All will indeed replace all instances of the find string with
  5724. the replace string throughout your document. If “Wrap Around” is not
  5725. checked, replacement will be done only below your current position in
  5726. the text. To prevent a single instance of the find pattern from being
  5727. replaced, select at least the first character of the instance in your
  5728. document just before Replace All (selecting all of it will do).
  5729.  
  5730.  
  5731. §    Multi–file searches
  5732. Any file in your project can be added to a list of files to be
  5733. searched. Files that are included in a multi–file search will have a
  5734. bullet • just to the left of the name in the project window.
  5735.  
  5736. “Coarse” setup of the multi–file search is done with the small buttons
  5737. in the lower–right of the Find dialog. These allow you to select all
  5738. files of a particular type—.c, ".h", <.h>, or plain text. The “None”
  5739. button will clear the multi–file search selection, and the “All” button
  5740. will add all of your project text files to the list. A counter in the
  5741. Find dialog shows how many files will be searched.
  5742.  
  5743. To “fine–tune” your list of files to be searched, hold down the
  5744. <Option> key and click on or drag over the files in the project window.
  5745. The cursor will change to an eye, and bullets beside the file names
  5746. will appear or disappear as you drag up and down over the files. There
  5747. is an illustration of this near the beginning of this chapter.
  5748.  
  5749. Once your files are selected (and you’ve entered what you want found
  5750. in the find string in the Find dialog) select Find In Next File or
  5751. click the equivalent button in the Find dialog. As the search
  5752. progresses, you will see the bullets beside file names in the project
  5753. window disappear as each file is searched. The counter in the Find
  5754. dialog will also count down the number of files remaining. If an open
  5755. file is searched by Find In Next File, it will be searched from the
  5756. beginning of the file. When an instance is found, Find Again will
  5757. locate other instances in the same file. To continue the multi–file
  5758. search with the next  file, select Find In Next File again.When all
  5759. files have been searched, you’ll hear a beep, the counter in the Find
  5760. dialog will read zero, and all bullets will be gone from the project
  5761. window.
  5762. Even if you don’t find anything, it puts on a nice show.
  5763.  
  5764. A <Command><period> will interrupt a multi–file search, and also clear
  5765. the list of files to be searched.
  5766.  
  5767. To generate a list of all instances of your search string, click
  5768. the "Batch" check box before doing your Find In Next File. Results
  5769. of the search will be shown to you in the "$tempStdOut" window
  5770. in the format «file name» line-number line-where-found, and
  5771. to view a particular instance in its original context click on the
  5772. line and use "Go to...".
  5773.  
  5774. Note that the "Find in Next File" button changes to read "Batch Find"
  5775. if you click the Batch checkbox in the Find dialog, and the corresponding
  5776. menu item under the Search menu changes as well.
  5777.  
  5778. By the way, your list of bulleted files in the project window can also
  5779. be used to remove those files from your project (see “Remove •'d Files”
  5780. in the “Projects” chapter), and used by a hAWK program as a list of
  5781. input files (see Appendix 2, and the hAWK User’s Manual on disk 2).
  5782.  
  5783.  
  5784.  
  5785.  
  5786.  
  5787.  
  5788.  
  5789.  
  5790.  
  5791.  
  5792.  
  5793.  
  5794.  
  5795.  
  5796.  
  5797. §    Skip '-' : excluding files from a search
  5798. In the Find dialog, the "Skip '-'" checkbox lets you exclude project files
  5799. that are marked with a dash '-' when carrying out a multi-file operation
  5800. such as searching. These dashes are primarily used to exclude files
  5801. from a dictionary build, and are placed by holding down the <Command>
  5802. key and clicking on the file's name in the project window. But you
  5803. may also wish to skip over these files when multi-file searching: if
  5804. so, you should turn this checkbox on in the Find dialog before
  5805. carrying out the search. Note if the "Skip '-'" option is on, then files
  5806. with a '-' beside them will not be passed to hAWK in your multi-file
  5807. selection, and they will not be removed from your project when
  5808. you pick "Remove •'d Files", whether or not they have bullets beside
  5809. them. Neither will they be selected or deselected for searching if
  5810. you click on the "All" or "None" buttons in the Find dialog.
  5811.  
  5812. If you have the "Skip '-'" checkbox turned on, then when you fine-tune
  5813. your multi-file selection by <Option>clicking in the project window
  5814. you will not be able to place bullets beside files that have a dash '-'
  5815. beside them. But note that "Skip '-'" takes precedence, so if you
  5816. put bullets beside files that have dashes and then turn on "Skip '-'",
  5817. those dashed files will not be included in multi-file operations.
  5818. At any time, the "Files to search:" number in the Find dialog
  5819. accurately shows the total number of files that will be searched,
  5820. so if "Skip '-'" is on then dashed files will not be included in the total.
  5821.  
  5822. To run a multi-file operation (such as the hAWK program
  5823. "$EchoFullPathNames", or a Batch Find) on just files that
  5824. are not marked with a '-':
  5825.     • select "Skip '-'"
  5826.     • mark the files with bullets (eg by clicking the All ".c" button
  5827.         or by holding down the <Option> key and clicking on project file
  5828.         names)
  5829.     • run the multi-file operation.
  5830.  
  5831. To run a multi-file operation on all EXCLUDED files, ie those
  5832. that are marked with a '-':
  5833.     • deselect "Skip '-'"
  5834.     • click the "All" button in the Find dialog
  5835.     • select "Skip '-'"
  5836.     • click the "None" button in the Find dialog
  5837.         (this will leave bullets beside files marked with a '-')
  5838.     • deselect "Skip '-'" again so the bulleted files won't be ignored
  5839.     • run the multi-file operation.
  5840.  
  5841. §    THINK Find commands
  5842. Located under the Search menu near the bottom, three commands allow
  5843. you to make use of the THINK Project Manager's "Find" results from
  5844. within EnterAct. To use these commands, you must use THINK C 6 or
  5845. later, and set up EnterAct as the Project Manager's editor as described
  5846. in Appendix 4 here.
  5847.  
  5848. After completing a "batch" find in THINK C, you can use the THINK
  5849. Find Again and THINK Find Previous commands to step through the
  5850. results. These two commands work only with the results of a
  5851. batch find.
  5852.  
  5853. To start or continue a multi-file search using the THINK Project
  5854. Manager's multi-file search rather than EnterAct's, use the
  5855. THINK Find In Next File commands after setting up the (non-batch)
  5856. search in the THINK Project Manager. Note this means you can perform
  5857. and even alternate between two separate multi-file searches, THINK's
  5858. and EnterAct's.
  5859.  
  5860. Find in THINK Reference does the same thing as the command of the
  5861. same name in the THINK Project Manager's editor: it passes your
  5862. currently-selected text over to THINK Reference, where you'll be
  5863. shown any entry it has on the name in question. Note this works only
  5864. with THINK Reference version 2 or later.
  5865.  
  5866. To use EnterAct's "Find in THINK Reference" command under any
  5867. circumstances, create a folder named "Tools" or "(Tools)" next
  5868. to EnterAct and drop an alias of Think Reference in it.
  5869.  
  5870. Find in Toolbox Assistant is much the same, just drop an
  5871. alias of QuickView in your Tools folder.
  5872.  
  5873. -    -    -    -    -    -    -    -    -    -    -    -
  5874. “Go” commands
  5875. -    -    -    -    -    -    -    -    -    -    -    -
  5876. Of the four “Go” commands under the Search menu, the most important
  5877. is the “Go to” command. This command allows you to jump to any marked
  5878. position in any project file, and since the marker position is
  5879. maintained as you edit, so is your ability to jump to it. The standard
  5880. suite of “go” capabilities is also available.
  5881.  
  5882.  
  5883. §    Go to Top/Bottom
  5884. The Go to Top and Go to Bottom menu commands do the same thing as
  5885. <command><up arrow> and <command><down arrow>, namely take you to
  5886. the top or bottom of your text window. They also function in the
  5887. project window.
  5888.  
  5889.  
  5890. §    Go to
  5891. The “Go to” command allows you to jump to a fixed position or a marker,
  5892. based on the text you have selected in your front window. The position
  5893. or marker can be in any project file.
  5894.  
  5895. For example, you can jump to a specific marker in a specific project
  5896. file with “Go to”. And there is an easy way to generate the file name
  5897. and marker name text (pick the marker from its popup marker menu while
  5898. holding down the <Shift> key), as explained in “Going to markers” a
  5899. couple of pages ahead. A typical link of this form in your code might
  5900. look like
  5901. ____
  5902.     /* See «MyProject Log» «Conversation with J.B. re New Features» */
  5903. ____
  5904. where the project file is “MyProject Log” and the marker name is inside
  5905. the second set of Euorpean quotes «». You could jump to the marker in
  5906. your “MyProject Log” file by clicking anywhere on the line mentioning
  5907. the file and marker and then selecting “Go to”. Selecting the
  5908. entire file name and marker name including the surrounding «» quotes
  5909. would also work. Since markers are maintained by most editors
  5910. (EnterAct, THINK C, and MPW for example), links of this form will also
  5911. be maintained as long as the marker exists and the file is in your
  5912. current project.
  5913.  
  5914. If both file name and marker name are in «» quotes, then both file
  5915. and marker name can be highly abbreviated, eg
  5916. ____
  5917.     /* See «Log»«J.B. News» */
  5918. ____
  5919. —as with regular lookup, your spelling just needs to be
  5920. “distinctively close”, in terms of runs of matching characters
  5921. when comparing against file and marker names in your project.
  5922.  
  5923. “Go to” also works with file names or marker names alone, or with line
  5924. and character positions in a file, or with file name followed by line
  5925. and character position. And it also accepts full path names.
  5926.  
  5927. The following terms are used below to help summarize selection
  5928. possibilities:
  5929.     • file_name:         the name of a project file, optionally enclosed in
  5930.     European-style quotes, ie «». Your selection will be extended to
  5931.     include any trailing file extension (such as “.c” or “.NOTES”),
  5932.     provided your basic selection is not by itself the name of a project
  5933.     file. This could also be a full path name.
  5934.     • marker_name:     the name of a marker in a project file, optionally
  5935.     enclosed in European style quotes «». Note the name of the marker
  5936.     should be specified, not the text (if any) that is selected when you
  5937.     jump to the mark.
  5938.     • text_position:     line number, optionally followed by character position
  5939.     on the line, for example 123 6 to specify the 123rd line in a file,
  5940.     just before the 6th character. The first line in a file is line 1, and
  5941.     the insertion point before the first character on a line is character
  5942.     position 1.
  5943.     • other_text:     by itself, text that is none of the above; following a
  5944.     file_name, text that is not a marker_name or text_position.
  5945.     • insertion_point: an empty selection.
  5946.  
  5947. “Go to” acts on selections in the following ways:
  5948.     • file_name     :            open the project file, or just bring it to the front if
  5949.                                     open
  5950.     • marker_name :        equivalent to selecting the marker from the
  5951.                                     window’s marker menu
  5952.     • text_position :        go to the position specified
  5953.     • file_name marker_name :     open the project file or bring it to front, and
  5954.                                     go to the marker specified
  5955.     • file_name text_position :     open the project file or bring it to front,
  5956.                                     and go to the position specified
  5957.     • file_name other_text :    open the project file or bring it to front, then
  5958.                                     use “Find” on the other_text in an attempt to
  5959.                                     locate it
  5960.     • other_text :            display a dialog in which to enter a line number
  5961.                                     to jump to.
  5962.     • insertion_point :    if the text of the link is quoted, ie file_name or
  5963.                                     marker_name if present are within «» quotes, then
  5964.                                     clicking anywhere on the line is sufficient to select
  5965.                                     the link for goto purposes. Otherwise, you will be
  5966.                                     shown the line number dialog, as with “other_text”
  5967.  
  5968. Note if both file name and marker name are in «» quotes you can use
  5969. extremely abbreviated versions of the names: the file name just has
  5970. to be "distinctively close" to the name of a project file, likewise
  5971. the marker name to a marker in that file.
  5972.  
  5973. Selections intended for the “Go to” command are called “Go to” selections
  5974. or “Go to” links in this manual. Here are some examples:
  5975.  
  5976.  
  5977. (a file_name link: note selecting the “.h” is optional)
  5978.  
  5979.  
  5980. (file_name in quotes followed by line number and character position
  5981. on line—for “Go to”, any insertion point on the line will do)
  5982.  
  5983.  
  5984.  
  5985. (instead of an insertion point, you can select all of the file_name
  5986. text_position)
  5987.  
  5988.  
  5989.  
  5990. (unquoted version of the same)
  5991.  
  5992.  
  5993.  
  5994. (file_name marker_name: with both in quotes, your selection can be
  5995. an insertion point anywhere on the line, here between the file and
  5996. marker names)
  5997.  
  5998.  
  5999.  
  6000.  
  6001. (without quotes, you must select the entire file_name marker_name)
  6002.  
  6003.  
  6004.  
  6005.  
  6006. (a marker-name link in the document “Proj Interface.DSGN”? Probably.
  6007. But it could also be a file name, or a marker in some other document.
  6008. The context of your current project and front window will determine
  6009. what  «Modifier keys»  is, and where you go to. Note for “Go to”
  6010. purposes, you could also just click in the line rather than selecting.
  6011.  
  6012. The one important restriction on “Go to” is that if you specify a file
  6013. name, the file you are going to must be in your currently open project.
  6014. If it isn’t, you can add it with the Add Files command.
  6015.  
  6016. To resolve ambiguity, file names take precedence over marker names.
  6017. And if you should have a marker name that looks like a text position,
  6018. enclosing it in quotes«» will force treatment as a marker name.
  6019.  
  6020. The file name can be the name of a PICT file, by the way, allowing you
  6021. to use single pictures as popup illustrations. And “Go to” works with
  6022. file names selected in the project window, performing the same as if
  6023. you double-clicked on the file name to open the file.
  6024.  
  6025. Spaces or tabs before, between, or after the components of a “Go to”
  6026. selection will be ignored. Hence the enclosing «» quotes are required
  6027. if a file name or marker  name begins or ends with “white space”.
  6028. Otherwise they’re optional, but quotes do help “Go to” selections to
  6029. stand out quietly from the surrounding text. And if both file name and
  6030. marker names are quoted, clicking anywhere on the line is
  6031. equivalent to selecting both parts for “Go to” purposes, a handy
  6032. shortcut. Quotes are included when you copy a marker name (and file
  6033. name) from a marker menu, as explained in “Going to markers” on the
  6034. next page.
  6035.  
  6036. If you have included a file name in your “Go to” selection but are
  6037. immediately shown the line number dialog instead of the desired file,
  6038. this means you haven’t yet added the file to your project. If you see
  6039. a message that the file couldn’t be found, this means the file has been
  6040. moved, renamed, or deleted since you added it to your project, and the
  6041. solution is to delete the file from your project and re-add it. If a
  6042. line that you go to seems to be the wrong line, this normally just
  6043. means that the file has been edited (lines added or deleted) since the
  6044. line number was specified. And if going to a marker doesn’t work, this
  6045. usually means that the marker has been deleted from the file (note that
  6046. if you delete the actual text marked then you lose the marker, even
  6047. if you immediately undo the delete).
  6048.  
  6049. File-name line-number links are of limited use, since the line numbers
  6050. can quickly become obsolete. Links of this form are however generated
  6051. by EnterAct and by hAWK programs when displaying lists of positions
  6052. (see the next section). File-name marker-name links are better for your
  6053. own use since their locations are maintained for you, and you’ll find
  6054. in the “Going to markers” section below an easy way to generate the
  6055. necessary text for them. And any existing mention of a file name or
  6056. marker name in any of your project documents is now a “Go to” link,
  6057. as you no doubt gathered -- just add the corresponding document to
  6058. your project.
  6059.  
  6060. §    Going to included files
  6061. To jump to the top of an included file such as
  6062. ____
  6063.     #include "thisheader.h"
  6064. ____
  6065. click on the line and select "Go to...".
  6066.  
  6067. Note if you have more than one header file with the same name
  6068. in your project you might not get the right one.
  6069.  
  6070. (To toggle between a source file and its corresponding header,
  6071. such as "File.cp"/"File.h", use <command><tab>.)
  6072.  
  6073. §    Going to text positions
  6074. Text positions compatible with the “Go to” command are displayed by the
  6075. Show Activities command, for example:
  6076. ____
  6077.     ¶60
  6078.     Sat Jan 16, 1993 10:51:48 pm PASTE «hAWK_FilesandClip.c» 390 4
  6079.     =>inserted 50 characters:
  6080.     «if (!dirs && !(fpb->ioFlAttrib & 16)) /* a file */»
  6081.     ¬
  6082. ____
  6083. To see the place where this paste took place, you would select
  6084. “«hAWK_FilesandClip.c» 390 4”, or just click in the line
  6085. somewhere, and then “Go to”. For details, please see the “Show
  6086. Activities” chapter. For now, note that the Show Activities
  6087. command can update the text positions (and even file names) for
  6088. you, to keep them as current as theoretically possible, which is to
  6089. say almost always useful.
  6090.  
  6091. Many hAWK programs generate file-name line-number text that is
  6092. compatible with the “Go to” command. For example, $CompareFiles shows
  6093. document differences in this form, and $XRef generates file name and
  6094. line number listings for C terms in your source code. Several of
  6095. the Index commands under the EnterAct menu also generate line
  6096. numbers.
  6097.  
  6098. Text positions can be used to link documents together, but you’ll
  6099. usually find it better to use marker names instead (see just below).
  6100. The reason is that marker positions are maintained as you edit files,
  6101. whereas line numbers can go out of date quickly.
  6102.  
  6103.  
  6104. §    Going to markers
  6105. The ability to “go to” any marker in any project file means you can
  6106. use a file name followed by a marker name as a true “hyperlink”,
  6107. especially useful for placing references to supporting documentation
  6108. in your source files or other documents.
  6109.  
  6110. To generate the necessary text for establishing a file-name marker-name
  6111. link:
  6112.     •    open the file that contains the marker
  6113.     •    hold down the <Shift> and <Option> keys, and click-and-drag in the
  6114.         window’s title bar to access the popup marker menu; select the marker
  6115.         you want
  6116.     •    the link, in the form «file name» «marker name» , is now on the
  6117.         clipboard, ready for pasting.
  6118.     •    (note <Shift> <Command> will also work when picking from a marker
  6119.         menu)
  6120.  
  6121. EnterAct places «» quotes around both the file name and the marker name.
  6122.  
  6123. To generate file-name marker-name link text for all markers in one or
  6124. more files, use the "Index Marker Names" command under the EnterAct
  6125. menu, as described in the "'Index' commands" chapter.
  6126.  
  6127. With quotes around both the file name and marker name, you can “select”
  6128. a file-name marker-name for “Go to” purposes by clicking anywhere on
  6129. the line if it's the only link on the file, or between the two quoted
  6130. bits of text otherwise. Your selection will be expanded to include the
  6131. quoted file name and marker names when you pick “Go to”. And with
  6132. both file and marker name in «» quotes you can use highly abbreviated,
  6133. even slightly incorrect versions of the names, provided those names
  6134. are distinctively close to the names of a file in your project and a
  6135. marker in that file (in terms of case-sensitive runs of matching
  6136. characters).
  6137.  
  6138.  
  6139.  
  6140.  
  6141.  
  6142.  
  6143.  
  6144.  
  6145.  
  6146.  
  6147.  
  6148.  
  6149.  
  6150.  
  6151.  
  6152.  
  6153.  
  6154.  
  6155.  
  6156.  
  6157.  
  6158.  
  6159.  
  6160.  
  6161.  
  6162.  
  6163.  
  6164.  
  6165. To go to the position referenced by a file-name marker-name link,
  6166. click on the line containing the link text,
  6167. and then issue a “Go to” (see next illustration).
  6168.  
  6169. On the chance that too many new things at once have pushed some old
  6170. things out the bottom of your memory stack, a reminder that to jump
  6171. to the definition of a term that’s in your current project dictionary
  6172. just <Option> double-click on it. File-name marker-name links are
  6173. mainly for jumping to places in your (unparseable) supporting
  6174. documentation.
  6175.  
  6176. Tip: if you want to be able to jump to an illustration in a text file,
  6177. mark its location and then copy the marker name for pasting elsewhere.
  6178.  
  6179.  
  6180. §    Go Back
  6181. This command takes you back to your last signficantly different
  6182. position in a text file. Usually the two positions will be in the same
  6183. file, and a typical use is to “toggle” back and forth within a function
  6184. between the spot where you’re creating code and the top of the function
  6185. where the locals and parameters are declared.
  6186.  
  6187. Whenever you move your insertion point or make a new selection, you
  6188. define a “significantly different” position to go back to if you: bring
  6189. a different text window to the front, or; click more than 3/4 of a
  6190. window away from your previous position. You can alter your current
  6191. position without spoiling the memory of your previous position by
  6192. inching along—click half a window away, scroll, click half a window
  6193. away, scroll….
  6194.  
  6195. You can also toggle between two positions in a file with markers, or
  6196. “go to” links, or by pressing <Enter> to switch between the top and
  6197. bottom ends of a large selection.
  6198.  
  6199.  
  6200.  
  6201.  
  6202.  
  6203.  
  6204.  
  6205.  
  6206.  
  6207.  
  6208.  
  6209.  
  6210.  
  6211.  
  6212.  
  6213.  
  6214.  
  6215.  
  6216.  
  6217.  
  6218.  
  6219.  
  6220.  
  6221.  
  6222.  
  6223.  
  6224.  
  6225.  
  6226.  
  6227.  
  6228.  
  6229.  
  6230.  
  6231.  
  6232.  
  6233.  
  6234.  
  6235.  
  6236.  
  6237.  
  6238.  
  6239.  
  6240.  
  6241.  
  6242.  
  6243. (Note the link text
  6244.     «hAWK User's Manual» «F        Running hAWK programs»
  6245. could have been abbreviated as say
  6246.     «hAWK Man»«running»
  6247. —when both file and marker name are in «» quotes, the file
  6248. and marker names just have to be reasonably close to the
  6249. actual names.)
  6250.  
  6251. -    -    -    -    -    -    -    -    -    -    -    - - -
  6252. Markers and the Locations menu
  6253. -    -    -    -    -    -    -    -    -    -    -    - - -
  6254. §    Introduction
  6255. A “marker” is a marked location in your text consisting of a start
  6256. point, an end point, and a name to be associated with the marked
  6257. position. Typically, you’ll place markers in your C source files
  6258. all at once with the Automark command, and you’ll place markers in
  6259. supporting documents one-at-a-time with the Mark command. Marks can
  6260. be placed in header files with Automark, but you may prefer to use
  6261. Mark. To bring up a popup menu of a window’s markers, hold down the
  6262. <Option> or <Command> key and click in the window’s title bar.
  6263.  
  6264. EnterAct's default behavior is to automatically generate markers
  6265. for all functions in source files and all struct/class definitions
  6266. in header files as you open or save the files, and to not save those
  6267. markers with the document. If you manually insert markers in a
  6268. document that goes in your project's rightmost (documentation)
  6269. pane, these markers will be saved with your document when you
  6270. save the file (this manual is an example). You can force EnterAct
  6271. to save source and header file markers with your files by
  6272. enabling the the “Save source/headers marks” option, but the
  6273. only use for this at present is to allow the “Index Marker Names…”
  6274. command to index marks in your source files.
  6275.  
  6276. At present EnterAct does not support #pragmas for inserting
  6277. special markers in source files.
  6278.  
  6279. Markers do stay attached to the proper position as you edit the file
  6280. around them, but any editing that’s done inside the marked range will
  6281. correspondingly expand or shrink the range associated with the marker.
  6282. If you remove all of the text that is within the marked range, you will
  6283. also remove the marker, and this is not undoable. Markers do not
  6284. survive cutting or pasting—they stay attached to the text only as long
  6285. as the text remains in the document. 
  6286.  
  6287. The Automark command is mainly useful to mark all of the function
  6288. definitions in a source file, though it has other options, and can be
  6289. used to mark a variety of C constructs, with the option of marking just
  6290. the first in a group. There is little need for this command, since
  6291. EnterAct's default behaviour is to mark source files for you without
  6292. your intervention.
  6293.  
  6294. Marker names can be used as links within or between files, in
  6295. conjunction with the “Go to” command. Called “Go to” links, these take
  6296. the form
  6297. ____
  6298.     «file name» «marker name»
  6299. ____
  6300. where the enclosing «» quotes are usually optional. Where a link is
  6301. present in your text, you can go to it by selecting the file name and
  6302. marker name (including «» quotes if present), or by clicking anywhere
  6303. on the line, and issuing the “Go to” command. For an easy way to
  6304. generate the text for these links, see “Copying marker names” below.
  6305. You’ll find details on using “Go to” links in the “‘Go’ commands”
  6306. chapter.
  6307.  
  6308. Please note your markers will be maintained properly only by editors
  6309. that implement MPW–compatible marks. This includes just about all
  6310. editors.
  6311.  
  6312.  
  6313. §    Mark
  6314. To place a single marker, select either an insertion point or the range
  6315. of text that you want remembered, and then select the Mark command.
  6316. You will be asked to supply or modify a name for the marker: click Add,
  6317. and then forever after you will be able to jump to that marker whenever
  6318. you want (marks are saved to disk and properly maintained).
  6319.  
  6320.  
  6321.  
  6322.  
  6323.  
  6324.  
  6325.  
  6326.  
  6327.  
  6328.  
  6329. §    Marker menus
  6330. Every document containing marks has a popup marker menu associated with
  6331. its window. To jump to a marker, hold down either the <Option> or
  6332. <Command> key or both and click-and-hold in the title bar of your
  6333. window. You’ll see a popup menu listing all of the markers attached
  6334. to your file. Pick one, and you go there. The markers are in
  6335. alphabetical order.
  6336.  
  6337.  
  6338.  
  6339.  
  6340.  
  6341.  
  6342.  
  6343.  
  6344.  
  6345.  
  6346.  
  6347.  
  6348.  
  6349.  
  6350.  
  6351.  
  6352.  
  6353.  
  6354.  
  6355.  
  6356.  
  6357.  
  6358.  
  6359.  
  6360.  
  6361.  
  6362.  
  6363.  
  6364. If the name of a marker is present in your text, you can also go to
  6365. it by selecting the name and using the Go to command, as explained in
  6366. the “‘Go’ commands” chapter.
  6367.  
  6368.  
  6369.  
  6370. §    Unmark
  6371. To remove one or more markers, select Unmark. You will be presented
  6372. with a list of markers to select for deletion. This list follows the
  6373. standard Macintosh rules for list selection: click with no keys held
  6374. down to select a single marker (this deselects any other selected
  6375. markers); click with the <Shift> key down to select a contiguous range
  6376. of markers while dragging the mouse; and click with the <Command> key
  6377. held down to select a marker that is away from other selected markers
  6378. (the markers in between are left unselected). 
  6379.  
  6380.  
  6381.  
  6382.  
  6383.  
  6384.  
  6385.  
  6386.  
  6387.  
  6388.  
  6389.  
  6390.  
  6391.  
  6392.  
  6393.  
  6394. To quickly remove all markers from a document, use the Automark command
  6395. with only the “Clear all present markers first” option checked.
  6396.  
  6397.  
  6398. §    Automark
  6399. This command is largely obsolete, and not recommended for any
  6400. purpose except removing all marks from a file that lives in the
  6401. documentation pane of a project. EnterAct's default behaviour is
  6402. to mark all source and header files for you automatically, and
  6403. this should be all you need.
  6404.  
  6405. This command works with any first-draft or compilable C file, whether
  6406. or not it has been added to your project.
  6407.  
  6408. The Automark command can be used to remove all marks from any file
  6409. (source or not), by checking just the “Clear all present markers first”
  6410. option.
  6411.  
  6412.  
  6413.  
  6414.  
  6415.  
  6416.  
  6417.  
  6418.  
  6419.  
  6420.  
  6421.  
  6422.  
  6423.  
  6424.  
  6425.  
  6426.  
  6427. If you wish to keep special markers that you have manually added, leave
  6428. “Clear all present markers first” without a check mark. When a
  6429. duplicate name or position is found while adding markers, the new entry
  6430. will replace the old one.
  6431.  
  6432. The “first of group only” checks have slightly different
  6433. interpretations: for #defines, it means mark only the first of a group
  6434. of consecutive #defines; for enum constants, it means mark only the
  6435. first within an enum {} statement; and for variables it means mark the
  6436. first of a group of consecutive variables, whether they occur in the
  6437. same statement or in separate statements. If you leave some types
  6438. unselected then EnterAct’s automarker won’t count them as separating,
  6439. say, two groups of variables or #define’s.
  6440.  
  6441. To keep things sane, there is a limit of 499 marks to a file. This is
  6442. a 9 foot popup menu, a bit tedious to scroll through even with a 68070.
  6443. Marker names are limited to 63 characters, but the range of text you
  6444. mark with the name can be as long as you want.
  6445.  
  6446.  
  6447.  
  6448.  
  6449. §    Copying marker names
  6450. To put text of the form «file name» «marker name» on the clipboard for
  6451. a particular marker, hold down the<Shift> key and either the <Option>
  6452. of <Command> key while clicking in the title bar of the marker’s window
  6453. to access the marker popup menu; selecting the marker from the popup
  6454. will put the text on your clipboard. This is the same as going to the
  6455. mark by selecting it from the popup marker menu, except that in
  6456. addition you hold down the <Shift> key.
  6457.  
  6458.  
  6459.  
  6460.  
  6461.  
  6462.  
  6463.  
  6464.  
  6465.  
  6466.  
  6467.  
  6468.  
  6469.  
  6470.  
  6471.  
  6472.  
  6473.  
  6474.  
  6475.  
  6476.  
  6477.  
  6478.  
  6479.  
  6480.  
  6481.  
  6482.  
  6483.  
  6484.  
  6485.  
  6486. Text of the form «file name» «marker name»  can be used with the Go
  6487. to command to jump to any marker in any project file, and variations
  6488. on this theme are available as detailed in the “‘Go’ commands” chapter.
  6489.  
  6490. §    The Locations menu
  6491. This menu allows you to mark and jump to up to 10 different locations.
  6492. You can mark positions in any text file, and they stay recorded in the
  6493. Locations menu until you delete them, independent of whatever project
  6494. you might have open. This is a generalization of the "Go Back" command,
  6495. allowing you to go back to any specific location.
  6496.  
  6497. If you edit files with some other editor, your remembered locations
  6498. may be thrown off, in which case you could delete and re-add them.
  6499. (Function and struct markers that are created automatically by
  6500. EnterAct are not thrown off if you edit files with some other editor.)
  6501.  
  6502. To add a position to the Locations menu:
  6503.     • select the position you want, and optionally some text there
  6504.     • pick Add Current Location from the Locations menu
  6505.     • a dialog will appear which allows you to set the position's
  6506.     name as it will appear under the Locations menu: if you selected
  6507.     some text at the position to be marked, that text will appear in
  6508.     the dialog. You can edit the name, put in an arbitrary name, or
  6509.     have no name at all--in this case, EnterAct will concoct a name
  6510.     for you, made up of the file name, line position, any enclosing
  6511.     function name and maybe other stuff.
  6512.  
  6513.  
  6514.  
  6515.  
  6516.  
  6517.  
  6518.  
  6519.  
  6520.  
  6521.  
  6522. To jump to a position you've added to the Locations menu:
  6523.     • pick it from the Locations menu.
  6524.  
  6525. To delete a position from the Locations menu:
  6526.     • go to the position (pick it from the Locations menu for example)
  6527.     • select Delete Current Location from the Locations menu
  6528.     • if the location can't be found, you will be asked if you want to
  6529.         delete the location from the menu.
  6530.  
  6531. When you hit the limit of 10 marked locations, you won't be able
  6532. to add any more until you delete one of the remembered locations.
  6533.  
  6534.  
  6535. -    -    -    -    -    -    -    -    -    -    -    -
  6536. Options, under the Edit menu
  6537. -    -    -    -    -    -    -    -    -    -    -    -
  6538.  
  6539. §    Introduction
  6540. You can change any of the options at any time. Defaults for the options
  6541. have been selected to give best performance under average conditions.
  6542. Options are saved with EnterAct itself rather than a project. Some of
  6543. them you’ll set once and forget, but the number of lookup windows and
  6544. the number of entries per lookup determine how cluttered your screen
  6545. can get, and how many alternate entries a lookup window will hold, so
  6546. you’ll vary these two numbers to suit particular circumstances.
  6547.  
  6548. For a discussion of “Safe switching under MultiFinder” see the next
  6549. chapter, “Switching to other applications”.
  6550.  
  6551. For a discussion of “Save activities to disk” see “Show Activities”
  6552. near the end, in the section “Turning activity recording on and off”.
  6553.  
  6554.  
  6555. §    Number of lookup windows
  6556. This box allows you to set the maximum number of lookup windows that
  6557. can appear on–screen at one time. For complicated situations you may
  6558. want more than 4, whereas on a small screen you may prefer fewer than
  6559. 4 to avoid clutter.
  6560.  
  6561.  
  6562.  
  6563.  
  6564.  
  6565.  
  6566.  
  6567.  
  6568.  
  6569.  
  6570.  
  6571.  
  6572.  
  6573.  
  6574.  
  6575.  
  6576.  
  6577.  
  6578.  
  6579.  
  6580.  
  6581.  
  6582.  
  6583. §    Number of entries per lookup window
  6584. The number in this box determines how may dictionary entries will be
  6585. retrieved in a lookup window, if your spelling does not match any term
  6586. in the dictionary exactly. If your spelling does match a term exactly,
  6587. all exact matches will be retrieved, up to a maximum of 60. You may
  6588. wish to temporarily increase the number in this box if your
  6589. recollection of the spelling of a term is shaky. On a regular basis,
  6590. you may prefer 3 or 5 entries rather than 4—a bit of experience will
  6591. tell.
  6592.  
  6593.  
  6594. §    Remembering window locations
  6595. By default, EnterAct will remember the window locations of all your
  6596. documents (saved in a small resource with the document). Also, you will
  6597. not be asked if you want to save changes to a document when you close
  6598. it if the only change is a change in window location (the “don’t
  6599. pester” option). You can take advantage of the remembered window
  6600. locations to work with groups of documents; arrange each group nicely
  6601. on the screen, and then if you later reopen the documents in that group
  6602. they will be arranged on–screen where you left them.
  6603.  
  6604.  
  6605.  
  6606.  
  6607.  
  6608.  
  6609.  
  6610.  
  6611.  
  6612.  
  6613.  
  6614.  
  6615.  
  6616.  
  6617.  
  6618.  
  6619.  
  6620.  
  6621.  
  6622.  
  6623.  
  6624.  
  6625.  
  6626. §    Long or short windows
  6627. If there is no remembered location for a document, or if you have
  6628. switched off the “Save document window locations” option, then a
  6629. newly–opened window will come up near the top of your screen, with a
  6630. relatively short or long length according to what you select in the
  6631. option “Windows open short/long by default”. You may not notice much
  6632. of a distinction if you have a small screen. This short/long option
  6633. always governs the appearance of new text windows, and of text files
  6634. created by other applications that have never been saved while using
  6635. EnterAct.
  6636.  
  6637.  
  6638. §    Reformat Selection options
  6639. Reformat Selection will rebreak the lines in a selection of text to
  6640. improve the appearance of the right margin. Aside from selecting a
  6641. “ragged right” or “full justification” look, you can also set the
  6642. maximum number of characters per line in the “Reformat line width” box.
  6643. The default of 74 gives a reasonable and printable line in Monaco 9.
  6644.  
  6645.  
  6646.  
  6647.  
  6648.  
  6649.  
  6650.  
  6651.  
  6652.  
  6653.  
  6654.  
  6655.  
  6656.  
  6657.  
  6658.  
  6659.  
  6660.  
  6661.  
  6662.  
  6663.  
  6664.  
  6665.  
  6666.  
  6667. §    Detect nested comment starts
  6668. This option is on by default, meaning that EnterAct will accurately
  6669. trap any single failure to properly start or end a comment, both while
  6670. building your dictionary and while balancing. If you are in the habit
  6671. of doubling up on comment starts, as in
  6672. ____
  6673.     /*#define Flag37 /* if defined, use SlowDraw */
  6674. ____
  6675. and if you are not willing to mend your ways, uncheck this option:
  6676. comment starts within a comment will then be ignored for dictionary
  6677. and balance purposes. Just make sure you type carefully!
  6678.  
  6679.  
  6680.  
  6681.  
  6682.  
  6683.  
  6684.  
  6685.  
  6686.  
  6687.  
  6688.  
  6689.  
  6690.  
  6691.  
  6692.  
  6693.  
  6694.  
  6695.  
  6696.  
  6697.  
  6698.  
  6699.  
  6700. §    Ignore 'ckid's
  6701. A 'ckid' is a resource that SourceServer uses to keep track of
  6702. whether a file is modifiable or read-only, and also if the file's
  6703. status has been changed from read-only to modifiable by an
  6704. editor while the file was checked out. EnterAct obeys these
  6705. resources (a "no pencil" icon appears in the window's display
  6706. box for read-only), and allows you to make changes to a
  6707. read-only file after you select the "Modify Read Only"
  6708. command.
  6709.  
  6710.  
  6711.  
  6712.  
  6713.  
  6714.  
  6715.  
  6716.  
  6717.  
  6718.  
  6719.  
  6720.  
  6721.  
  6722.  
  6723.  
  6724.  
  6725.  
  6726.  
  6727.  
  6728.  
  6729.  
  6730.  
  6731. Selecting "Ignore 'ckid's" in the Options dialog will force
  6732. EnterAct to completely ignore these resources. You’ll be able
  6733. to edit a file that was checked out as read-only, and the
  6734. SourceServer will never know. This can really screw things up.
  6735. Don’t do it. There, you’ve been warned.
  6736.  
  6737. §    Relocate files automatically
  6738. When this box is unchecked (the default), EnterAct will present
  6739. a dialog asking you to relocate a file whenever it loses track of
  6740. where a file is. This typically happens when you trash a whole
  6741. folder and replace it with a newer version. If you check this
  6742. box, then if EnterAct loses track of a file it will attempt to
  6743. relocate it without your help, by searching down from the top
  6744. level of the disk where it was last seen. If this doesn't work,
  6745. you'll still be asked to help.
  6746.  
  6747. Check the "Relocate files automatically" box only if you're sure that
  6748. each of your source files is uniquely named on the disk where you've
  6749. stored it. If you can't guarantee that, then please leave the box unchecked,
  6750. and put up with the occasional request to relocate a file -- it's no
  6751. more painful than resetting file paths with Code Warrior.
  6752.  
  6753. Note that if you just move a folder around on the same disk,
  6754. or rename a folder, EnterAct will still keep track of where
  6755. the contained files are. To make EnterAct lose track of a file,
  6756. you have to move it to a different folder, including the case of
  6757. trashing a folder and replacing it with one that has the same name.
  6758. (What about renaming the file? From EnterAct's point of view,
  6759. if you rename a file then it's a different file, and you'll have to
  6760. add it separately to your project.)
  6761.  
  6762. §    Automark source files
  6763. The "AutoMark source..." check box will create marks for all functions
  6764. in a source file when you open it, and marks for struct and class
  6765. definitions in headers. The marks are redone (to pick up new functions
  6766. etc) whenever you access the popup marker menu for a file after
  6767. editing it, or when you Save a file.
  6768.  
  6769. “Automark source/headers...” is ON by default.
  6770.  
  6771.  
  6772.  
  6773.  
  6774.  
  6775.  
  6776.  
  6777.  
  6778.  
  6779.  
  6780.  
  6781.  
  6782.  
  6783.  
  6784.  
  6785.  
  6786.  
  6787.  
  6788.  
  6789.  
  6790.  
  6791.  
  6792. §    Save source/headers marks
  6793. You can force EnterAct to save source and header file markers
  6794. with your files by enabling the the “Save source/headers marks”
  6795. option, but the only use for this at present is to allow the
  6796. “Index Marker Names…” command to index marks in your source files.
  6797.  
  6798. “Save source/headers marks” is OFF by default.
  6799.  
  6800. §    Append arguments for automarked functions
  6801. This checkbox (see illustration above) controls whether summaries of
  6802. arguments to functions and methods are appended in the popup marker
  6803. menu for source and header files. This is ON by default. It's handy for
  6804. distinguishing between functions with the same name that take
  6805. different arguments, and for a quick reminder of what arguments a
  6806. function takes.
  6807.  
  6808. Addin the argument summaries takes a while, so if you have a slow
  6809. machine you might prefer to turn this option off. It's OK on a 68040
  6810. running at 25Mhz.
  6811.  
  6812. §    Record Find, Find Again, Find Definition
  6813. If you do a lot of Find's and jumping to definitions, these activities
  6814. can clutter up your activity log. Turn this option off if you'd rather
  6815. have your activity log hold just the more interesting activities, and
  6816. don't mind losing some information about where you went.
  6817.  
  6818. This option is ON by default.
  6819.  
  6820.  
  6821.  
  6822.  
  6823.  
  6824.  
  6825.  
  6826.  
  6827.  
  6828.  
  6829.  
  6830.  
  6831.  
  6832.  
  6833.  
  6834.  
  6835.  
  6836.  
  6837.  
  6838.  
  6839.  
  6840.  
  6841. -    -    -    -    -    -    -    -    -    -    -    -
  6842. Switching to other applications
  6843. -    -    -    -    -    -    -    -    -    -    -    -
  6844. §    Under the Finder (System 6)
  6845. There are some nifty INIT’s that will let you switch between
  6846. applications under the Finder almost as quickly and easily as if you
  6847. were using MultiFinder—On Cue and Master Juggler come to mind.
  6848. (OK, you got me - this manual was started in 1990, and there are
  6849. a few "fossils" here and there....)
  6850.  
  6851. Whatever means you employ to switch to another application from
  6852. EnterAct while under the Finder, you will be asked if you wish to save
  6853. any documents that need saving, and they will all be closed. The
  6854. situation with MultiFinder (or System 7) is different , since documents
  6855. can be left open when switching to another application.
  6856.  
  6857.  
  6858. §    Under MultiFinder (or System 7 or later)
  6859. If you switch from EnterAct to some other application while under
  6860. MultiFinder or System 7, you will not be required to close your
  6861. documents. This means that while using the other application you could
  6862. attempt to access documents that you have left open in EnterAct. If
  6863. this potential conflict weren’t handled, you could end up working with
  6864. two different versions of the same document, and inevitably you would
  6865. lose one version.
  6866.  
  6867. One solution to this problem would be to prevent you from opening that
  6868. document with any other application if it is left open in EnterAct.
  6869. This restrictive “my file and you can’t have it” attitude is
  6870. appropriate if an application is meant for use on a network, where
  6871. several people could want access to the same file at once.
  6872.  
  6873. However, EnterAct is not meant to provide source code management
  6874. with multiple users (many packages such as Projector, VOODOO, MW
  6875. CodeManager etc can be used in addition to EnterAct to provide full
  6876. source code management), so it does not take this approach. Instead,
  6877. when you switch, all open documents are quietly saved if they need
  6878. saving and have ever been saved before (“untitled” documents present
  6879. no problem—you can’t get at them with another application). In
  6880. addition, when you return to EnterAct, EnterAct will check your disk to
  6881. see if you have altered any of the open documents while you were
  6882. away—if so, they will be quietly reloaded. EnterAct, if effect, opts for
  6883. the “low man on the totem pole” position when it comes to having
  6884. control over file access, and does the necessary behind–the –scenes
  6885. work to allow you to leave files open and still be able to open and
  6886. change them with other applications.
  6887.  
  6888. To make this bulletproof, it will be safest if you close all text
  6889. documents when leaving the other application, since that other
  6890. application will typically not be able to compensate for files being
  6891. changed “behind its back” in EnterAct.
  6892.  
  6893. You can, if you wish, defeat this protection by unchecking the “Safe
  6894. switching under MultiFinder” option in the Options dialog. However,
  6895. EnterAct will not restrict access to open files when you switch, so
  6896. you will be entirely responsible for ensuring that you don’t end up
  6897. with two versions of the same file floating around. Closing all open
  6898. text documents before switching would be sufficient.
  6899.  
  6900.  
  6901.  
  6902.  
  6903.  
  6904.  
  6905.  
  6906.  
  6907.  
  6908.  
  6909.  
  6910.  
  6911.  
  6912.  
  6913.  
  6914.  
  6915.  
  6916.  
  6917.  
  6918.  
  6919.  
  6920.  
  6921.  
  6922. Safe switching protection can also be defeated on a per–switch basis,
  6923. by holding down any of the <Shift>, <Option>, or <Command> modifier
  6924. keys while you switch. Holding down a modifier key while you switch
  6925. out from EnterAct means that unsaved changes to files will be left
  6926. unsaved, and when you return to EnterAct any files open in EnterAct
  6927. that were changed elsewhere will not be updated for you on–screen.
  6928. Holding down a modifier key while returning to EnterAct will prevent
  6929. just the updating on–screen of any files that were changed elsewhere.
  6930. This is, on rare occasions, handy if you change a file with some other
  6931. application, realise you’ve made a mistake but can’t revert, and wish
  6932. to recover the version of your file that’s still open in EnterAct.
  6933.  
  6934. If you wish to have several people working on the same source
  6935. files at the same time with EnterAct, your best approach is to
  6936. use SourceServer or some other version of source control that
  6937. uses 'ckid's to mark files as modifiable or read-only.
  6938.  
  6939. §    Check the disk for changes
  6940. When you edit source (.c or .h) files that are in an EnterAct project
  6941. with some other application, select Update Dictionary when
  6942. you reopen the project to ensure that your dictionary is brought up
  6943. to date, unless you clearly recollect that you didn’t change anything
  6944. outside of a function body. This update typically takes only a few
  6945. seconds.
  6946.  
  6947. Only the project you have open will track which files are changed, so
  6948. if you switch to a different project you will also need to select
  6949. Update Dictionary to rebuild the dictionary if any .c or .h
  6950. files in the project were changed while the project was not open,
  6951. whether or not the files were changed with EnterAct.
  6952.  
  6953. Experience suggests that it's more efficient to update your EnterAct
  6954. dictionary when you notice that it's producing lookup that's out of
  6955. date (unless more than one person is involved, in which case you may
  6956. be better off doing the Update routinely).
  6957.  
  6958. §    Working with THINK C
  6959. This section describes working with THINK C as a separate application:
  6960. to use EnterAct as a replacement for THINK’s own editor (the “use
  6961. external editor” Edit option in THINK C version 6 or later) please see
  6962. Appendix 4.
  6963.  
  6964. If you adopt EnterAct as your C editor of choice, you’ll often change
  6965. several files with EnterAct over an extended period, and then switch
  6966. to THINK C to bring your application up to date. Fortunately, there
  6967. is no need to keep exact track of which files you change, since THINK
  6968. C’s Make command can do this for you. Call up the Make dialog, click
  6969. the “Use Disk” button, and, after the brief wait while THINK C checks
  6970. the modification dates of your project files, click the “Make” button
  6971. to bring your THINK C project fully up to date. If you remember exactly
  6972. which files were changed, you can instead select them one by one in
  6973. the project window and use the “Compile” command to update your THINK
  6974. C project.
  6975.  
  6976. Conversely, if you use THINK C to make some changes to your source
  6977. files, you can bring your EnterAct project fully up to date by
  6978. selecting the Update Dictionary command from the EnterAct
  6979. menu, as mentioned above. Note this step is not necessary if your
  6980. changes while in THINK C were restricted to function bodies, which
  6981. should often be the case. This is because EnterAct does nothing with
  6982. function bodies except check them for balance in a few key delimiters.
  6983.  
  6984. Editing files with THINK C, or any other editor besides EnterAct, will
  6985. compromise your ability to revert files to earlier versions with
  6986. EnterAct (see the “Show Activities” chapter). That’s worth remembering,
  6987. but in practice the need to revert a file is so rare that you shouldn’t
  6988. let it influence your editing. If you do need to revert files regularly,
  6989. you're better off using some sort of version control software.
  6990.  
  6991. -    -    -    -    -    -    -    -    -    -    -    -
  6992. Show activities
  6993. -    -    -    -    -    -    -    -    -    -    -    -
  6994. §    Introduction
  6995. EnterAct will, at your option, keep track of your recent activities
  6996. in full detail. The Show Activities command under the Edit menu
  6997. generates a window holding descriptions of those activities, with
  6998. details in plain English of what, when, and where. Here are three
  6999. typical entries from the “••Recent Activities••” window generated by
  7000. Show Activities:
  7001. ____
  7002.  
  7003. ¶148
  7004. Tue Jan 12, 1993 8:22:23 pm OPEN «PICT saving»
  7005. ¬
  7006. ¶149
  7007. Tue Jan 12, 1993 8:23:17 pm CUT «PICT saving» 45 1 (temp)
  7008. <=deleted 289 characters:
  7009. «/* save pict "dataH" under the full path name "fileName", on
  7010. the volume "volumeName" */
  7011.     /* open the file, which should already exist */
  7012.     pb.ioCompletion = 0L;
  7013.     pb.ioNamePtr = (StringPtr)fileName;
  7014.     pb.ioVRefNum = 0;
  7015.     pb.ioVersNum = 0;
  7016.     pb.ioPermssn = 3; /* = fsRdWrPerm */
  7017.     pb.ioMisc = 0L;»
  7018. ¬
  7019. ¶150
  7020. Tue Jan 12, 1993 8:23:21 pm CLOSE «PICT saving»
  7021. ¬
  7022.  
  7023. ____
  7024. —where, for example, “CUT «PICT saving» 45 1 (temp)” means characters
  7025. were cut from the document “PICT savings” starting at line 45 position
  7026. 1, and the cut was temporary, ie not saved to disk—if it had been,
  7027. there would have been a SAVE before the CLOSE. Both file names and data
  7028. are enclosed in European-style quotes «».
  7029.  
  7030. Activity records are kept on disk in the log file “EnterAct Recent
  7031. Activities”. This file is created and managed for you, and is preserved
  7032. between sessions. Your most-recent 10,240 activities will be recorded
  7033. in full detail, up to the limits of 65,535 characters per insert or
  7034. delete, and a total of 1,310,720 characters of inserts and deletes for
  7035. the 10,240 activities (typically only 1/4 or less of that is needed).
  7036. Everything of interest, including all edits, searches,
  7037. open/close/save/save as, switching in and out, etc will be recorded.
  7038.  
  7039. Armed with a display of your recent activities, you will typically be
  7040. able to:
  7041.     •    remind yourself of what you did recently (another form of “context
  7042.         restoration”)
  7043.     •    selectively undo or recover the contents of any recent insert or
  7044.         delete
  7045.     •    generate a reverted version of a file, back to a particular activity
  7046.         (multiple files can be done one file at a time, back to different
  7047.         activities)
  7048.  
  7049. To turn the recording of activities off temporarily, select the menu
  7050. item named Recording activities under the Edit menu: it will change
  7051. to read Not recording activities. This is a toggle, and selecting it
  7052. again will turn recording back on. Your recording status is remembered
  7053. between sessions.
  7054.  
  7055. If you’re just interested in a quick first look, skim through the
  7056. “What’s shown” and “Reviewing activities” sections later in this
  7057. chapter.
  7058.  
  7059. To revert one or more files, you’ll need to follow the checklist in
  7060. the “Reverting a file” section, since the procedure is relatively
  7061. lengthy. For other uses of the “••Recent Activities••” window, an
  7062. understanding of the format of a displayed activity is all you really
  7063. need. Many obvious points are explained at length below, both to scrub
  7064. away the fuzziness from some intuitive notions and to introduce you
  7065. gently to what is, at heart, a simple way of keeping track of what
  7066. you’ve done recently.
  7067.  
  7068.  
  7069. §    What’s recorded
  7070. Full details on the following activities are recorded in the log file
  7071. “EnterAct Recent Activities”:
  7072.     •    all edits which affect your text, including typing, Cut, Paste,
  7073.         Paste Selection Behind, Undo, and replacements done with any of the
  7074.         replacement commands under the Search menu. The only notable edit
  7075.         exception is Copy
  7076.     •    all search results, in one or multiple files
  7077.     •    session start and end, switching in and out, running a Drag_on Modul
  7078.     •    Open, Close, Save, Save As, Revert, for text, lookup, PICT, and
  7079.         project windows (when applicable)
  7080.     •    Go to, Go Back, Go to Top, Go to Bottom, and jumping to a definition
  7081.  
  7082. After starting EnterAct at least once, you’ll find your log file in
  7083. the same folder as EnterAct itself, and you’ll probably be able to
  7084. identify it as a “log” file just by its icon. Note that it is not a text
  7085. file, at least not entirely, and its contents can be shown only with
  7086. EnterAct’s Show Activities command.
  7087.  
  7088. For each activity, the following information will be recorded, if
  7089. appropriate:
  7090.     •    the name of the activity (eg TYPING, SAVE, RUN DRAG_ON MODULE)
  7091.     •    the time at which it occurred
  7092.     •    the name of the file in which it occurred
  7093.     •    the position in the file at which it occurred, specifically the
  7094.         starting position if it was an insert, delete, or Find of some sort
  7095.     •    for inserts and deletes, the full contents, and the size of the edi
  7096.     •    for search and replace, the found text and the replacement text
  7097.     •    for Save As only, the previous name of the window.
  7098.  
  7099. Inserts and deletes are recorded as separate activities, even if they
  7100. result from a single command. For example, pasting over a selection
  7101. will be recorded as a delete followed by an insert:
  7102. ____
  7103. ¶7
  7104. Wed Jan 13, 1993 9:27:52 pm PASTE «Untitled-1» 1 1
  7105. <=deleted 35 characters:
  7106. «This text was deleted when pasting.»
  7107. ¬
  7108. ¶8
  7109. Wed Jan 13, 1993 9:27:52 pm PASTE «Untitled-1» 1 1
  7110. =>inserted 38 characters:
  7111. «This text was pasted over a selection.»
  7112. ¬
  7113. ____
  7114. The recorded file position of an edit is of course the position as
  7115. calculated at the time the activity occurred. Thus, for example, if
  7116. you inserted some text at line 100, character position 3 in a file,
  7117. the recorded position will be line 100, position 3. However, a
  7118. subsequent edit before the position of that insert, for example a
  7119. delete of lines 20 through 29 in the same file, will alter the position
  7120. you would want to examine if you now went looking for that insert,
  7121. assuming you saved your file. Instead of finding the inserted text at
  7122. line 100, you would find it at line 90. This is called the “updated”
  7123. position of the activity. As you’ll see in “What’s shown” below, you
  7124. have the choice of showing either original or updated positions.
  7125.  
  7126.  
  7127. §    Recording limitations
  7128. EnterAct does not record activities carried out in other applications,
  7129. in particular changes to text files. Editing files with some other
  7130. editor (such as THINK C) will compromise your ability to recover
  7131. reverted versions of files using EnterAct’s multiple undo capability,
  7132. in the following ways:
  7133.     •    if the edits elsewhere involved adding or removing lines, you will
  7134.         probably not be able to usefully revert the file with EnterAct
  7135.     •    if the edits elsewhere were fairly small, and did not involve adding
  7136.         or removing lines, then you will probably be able to recover a useful
  7137.         reverted version with EnterAct, but the small changes you made
  7138.         elsewhere will not be reflected in the reverted version.
  7139.  
  7140. Only your most-recent 10,240 activities will be recorded in the
  7141. “EnterAct Recent Activities” log file. The contents of your inserts
  7142. and deletes will be recorded up to a limit of 1,310,720 characters
  7143. total for all activities. In addition,
  7144. inserts and deletes will be fully recorded only if they do not
  7145. exceed 65,535 characters. For edits exceeding this limit, only the
  7146. first 1,024 characters will be recorded for reference.
  7147.  
  7148. Typically:
  7149.     •    10,240 activities represents several days of work. If you want to
  7150.         estimate how far back your activity log goes, bear in mind that inserts
  7151.         and deletes are recorded as separate activities, a run of characters
  7152.         typed without changing the insertion point counts as a single insert,
  7153.         and usually for every insert or delete there is one activity of some
  7154.         other kind such as a save or search. For example, at 4 activities
  7155.         per minute on average, you'll be logging your last 40 hours.
  7156.     •    large edits are rare enough that you won’t run into the recording
  7157.         limits. Your average number of characters per activity will probably
  7158.         be under 50, and, if you’re slightly paranoid like the rest of us, you
  7159.         will probably deal will very large edits by using Save As rather than
  7160.         Cut and Paste.
  7161. Minor activities, such as scrolling or changing windows, are not
  7162. recorded.
  7163.  
  7164. To avoid cluttering your activity log, a Replace All that is just used
  7165. for counting purposes is not recorded in detail. 
  7166.  
  7167. Based on personal experience, the limitation that most affects the
  7168. quality of recorded activities is of the “is it plugged in?” variety.
  7169. If you turn recording off temporarily, remember to turn it back on
  7170. again later!
  7171.  
  7172.  
  7173.  
  7174. §    Showing your recent activities
  7175. Selecting Show Activities from the Edit menu produces the following
  7176. dialog:
  7177.  
  7178.  
  7179.  
  7180.  
  7181.  
  7182.  
  7183.  
  7184.  
  7185.  
  7186.  
  7187.  
  7188.  
  7189.  
  7190.  
  7191.  
  7192.  
  7193.  
  7194. Select the “updated current positions” button to have activity
  7195. positions updated as much as possible. Select the “originally recorded
  7196. positions” button to leave line numbers and character positions
  7197. unchanged from their originally recorded values. For review or single
  7198. undo, you’ll want updated positions, but in order to perform a multiple
  7199. undo the original positions are required.
  7200.  
  7201. You may show up to 10,240 of your recent activities, and as you alter
  7202. the number of activities to show the “Memory needed” display at bottom
  7203. of the dialog will update. Showing a few activities will take 700K
  7204. or so of memory, and showing all 10,240 may require a couple of
  7205. meg or more. If you will need more memory than is available, try
  7206. closing all windows including your current project.
  7207.  
  7208. When you click the OK button, a plain-English description of your
  7209. activities will be generated, and shown to you in a window titled
  7210. either “••Recent Activities••” if you selected original positions, or
  7211. “••Recent Activities (updated)••” if you selected updated positions.
  7212.  
  7213. If you’re only interested in your last few activities, adjusting the
  7214. number of activities to show to a small number will reduce the time
  7215. it takes to generate this description.
  7216.  
  7217. "Show full path names for files" is useful if you have more that one
  7218. file with the same name. This will require slightly more memory for
  7219. all that extra text.
  7220.  
  7221.  
  7222. §    What’s shown
  7223. Here’s are some typical entries selected from a “••Recent Activities••”
  7224. display:
  7225. ____
  7226. ¶60
  7227. Sat Jan 16, 1993 10:51:48 pm PASTE «hAWK_FilesandClip.c» 390 4
  7228. =>inserted 50 characters:
  7229. «if (!dirs && !(fpb->ioFlAttrib & 16)) /* a file */»
  7230. ¬
  7231. ¶359
  7232. Sun Jan 17, 1993 5:53:14 pm SAVE AS «HuffCode.c»
  7233. Previous name was: «Untitled-1»
  7234. ¬
  7235. ¶858
  7236. Sun Jan 17, 1993 11:47:09 pm GO TO «EnterAct log» 1417 1
  7237. ¬
  7238. ¶868
  7239. Sun Jan 17, 1993 11:50:28 pm OPEN «CEDAR_Files.c»
  7240. ¬
  7241. ¶869
  7242. Sun Jan 17, 1993 11:50:28 pm FIND DEFINITION «CEDAR_Files.c» 3035 1
  7243. «GetSwitchOutTime»
  7244. ¬
  7245. ¶870
  7246. Sun Jan 17, 1993 11:50:43 pm FIND «CEDAR_Files.c» 43 23
  7247. «SwitchOutTime»
  7248. ¬
  7249. ¶926
  7250. Mon Jan 18, 1993 12:02:54 am SWITCH OUT 
  7251. ¬
  7252. ¶927
  7253. Mon Jan 18, 1993 12:07:31 am SWITCH IN 
  7254. ¬
  7255. ¶1001
  7256. Tue Jan 19, 1993 11:09:56 pm END OF SESSION 
  7257. ¬
  7258. ¶1002
  7259. Wed Jan 20, 1993 8:00:49 pm START OF SESSION 
  7260. ¬
  7261. ____
  7262. The first line of the activity record begins with “¶”, and is followed
  7263. by the activity number. The oldest activity shown is number 1, followed
  7264. by later (younger) activities up to the last thing you did, and its
  7265. number may be as high as 10,240.
  7266.  
  7267. The second line of the activity record shows the date and time,
  7268. followed by the name of the activity. These are present for all
  7269. activities, and for some activities (such as SWITCH OUT ) that may be
  7270. all there is before the ending “¬”.
  7271.  
  7272. If the activity involves a file or window, its name will be shown next
  7273. inside European style «» quotes. And if the activity relates to a
  7274. specific position in the file, this will be shown after the file name.
  7275. The position is for the start of the activity, and consists of the
  7276. starting line number followed by the character position at which the
  7277. activity started on that line. The first line in the file is line 1,
  7278. and the position before the first character on a line is position 1.
  7279.  
  7280. The third and following lines hold the data, if any, associated with
  7281. the activity. For inserts and deletes, the data will be preceded by
  7282. either “<=deleted xx characters” or “=>inserted xx characters” where
  7283. xx is the number of characters. In rare cases where the entire edit
  7284. could not be recorded, this will be followed by a number telling how
  7285. many characters of the edit have been retained, for example
  7286.     =>inserted 98765 characters (1024 shown)
  7287.  
  7288. The contents of an insert or delete will be trimmed if:
  7289.     •    the edit exceeds 65,535 characters; in this case, only the first
  7290.         1,024 characters will be recorded
  7291.     •    total recorded data would exceed 1.3Meg; in this case the
  7292.         data recorded for the oldest edits will be progressively trimmed until
  7293.         enough room is freed up to record the newest edit. The governing
  7294.         assumption is that the older an edit is, the less important it is,
  7295.         regardless of size. This approach has been chosen so that you will
  7296.         retain multiple-undo capabilities as far back as possible.
  7297.  
  7298. The data associated with the activity is enclosed in European-style
  7299. quotes «», and no characters are appended or altered inside the quotes,
  7300. though as described above characters may on rare occasions be trimmed
  7301. from the end.
  7302.  
  7303. Each activity finishes up with a “¬”, on a line by itself.
  7304. The SAVE AS  activity has a special format, with the second line
  7305. containing SAVE AS  followed by the new file name, and the third line
  7306. giving the previous name of the window, with accompanying text that
  7307. makes this clear.
  7308.  
  7309. The number of activities shown will often fall a few short of the
  7310. number you requested (typically by 1 or 2 per 100). These “missing
  7311. activities” were originally records of your typing. A sequence of
  7312. characters typed without moving the insertion point other than by
  7313. typing counts as, and is recorded as,  a single activity. However,
  7314. there is no such Macintosh event as “end of typing”, and EnterAct is
  7315. slightly conservative in its estimate of when you have finished typing
  7316. in a particular spot. Basically, any recordable activity is treated
  7317. as an “end of typing” event if typing was going on. For example, a Save
  7318. while typing would trigger a recording of your typing up to that point.
  7319. If you then continue typing in the same place, that typing record will
  7320. later be deleted, and a complete record of all your typing in the same
  7321. place will eventually be made. Normally this is of no consequence, and
  7322. now that you know what’s happening you shouldn’t let it affect you in
  7323. the slightest.
  7324.  
  7325.  
  7326.  
  7327. §    Temporary, obsolete, and undone activities
  7328. Though not recorded, the “current relevance” of any activity which
  7329. refers to a specific place in a file is inferred when you Show
  7330. Activities. As a result of later activities up to the time at which
  7331. you show them, an earlier activity may end up being currently classed
  7332. as:
  7333.     •    permanent; the document in which it occurred was saved to disk after
  7334.         the activity in question (ie not closed without saving, or unsaveable
  7335.         such as a lookup window). More accurately, an activity is permanent
  7336.         unless it falls into one of the following categories. “Permanent” is
  7337.         the default category, and permanent activities are not indicated in
  7338.         any special way in activity records.
  7339.     •    temporary; the window in which the activity occurred was
  7340.         subsequently closed without saving, but some version of the document
  7341.         currently exists on disk, so that in principle at least the activity
  7342.         still has a recoverable context. 
  7343.     •    obsolete; not only was the window closed after the activity, but
  7344.         no reasonable version of the document now exists on disk. This can
  7345.         happen if you insert text into a new window and then close it without
  7346.         saving, or if you edit an unsaveable window (such as a lookup window).
  7347.         This can also happen when you use Save As to replace an existing file
  7348.         “OldFile” with a new version; at that point, all previous activities
  7349.         relating to “OldFile”, especially inserts and deletes, become obsolete
  7350.         since they were later overwritten by a new version and hence no longer
  7351.         have a recoverable context in any meaningful sense.
  7352.     •    undone; a permanent activity that was subsequently reversed with
  7353.         the Undo command. All temporary and obsolete edits have already been
  7354.         “undone”, in the sense that from the point of view of your disk files
  7355.         they never happened.
  7356.  
  7357. If a file is open when you select Show Activities, all edits from the
  7358. last save or open of that file up to the present will be classed as
  7359. permanent. However, if you subsequently close the file without saving
  7360. it and then reselect Show Activities, you will find that those edits
  7361. have been reclassified as temporary. And if you later save over the
  7362. file by using Save As, effectively replacing its contents with the
  7363. contents of some other file, then the activities will be reclassified
  7364. as obsolete.
  7365.  
  7366. If an activity is classed as temporary, obsolete, or undone, you’ll
  7367. see “(temp)", “(obs)", or “(undone)" respectively in the activity
  7368. record, following the file name and position numbers. Here are some
  7369. examples to help bring this into focus, each followed by a brief
  7370. explanation:
  7371. ____
  7372. ¶25
  7373. Wed Jan 20, 1993 9:55:07 pm OPEN «HuffCode.c»
  7374. ¬
  7375. ¶26
  7376. Wed Jan 20, 1993 9:55:37 pm TYPING «HuffCode.c» 4 1 (temp)
  7377. =>inserted 69 characters:
  7378. «This text was typed into "HuffCode.c",and then the typing was     
  7379. undone.»
  7380. ¬
  7381. ¶27
  7382. Wed Jan 20, 1993 9:55:37 pm UNDO «HuffCode.c» (temp)
  7383. ¬
  7384. ¶28
  7385. Wed Jan 20, 1993 9:55:46 pm CLOSE «HuffCode.c»
  7386. ¬
  7387. ____
  7388. (Note that the document “HuffCode.c” was closed without saving. The
  7389. typing is classed as temporary, which takes precedence over the undoing
  7390. of the typing. The same would be true of an obsolete edit that was
  7391. undone—it would be classed as obsolete.)
  7392.  
  7393. ____
  7394. ¶31
  7395. Wed Jan 20, 1993 9:58:16 pm OPEN «Untitled-2»
  7396. ¬
  7397. ¶32
  7398. Wed Jan 20, 1993 9:58:46 pm TYPING «Untitled-2» 1 1 (obs)
  7399. =>inserted 87 characters:
  7400. «This text was typed into the window "Untitled-2", which was
  7401. then closed without saving.»
  7402. ¬
  7403. ¶33
  7404. Wed Jan 20, 1993 9:58:48 pm CLOSE «Untitled-2»
  7405. ¬
  7406. ____
  7407. (Text was entered in a window that had never been saved to disk, and
  7408. then the window was closed without saving. The context of this activity
  7409. has been lost for good.)
  7410.  
  7411. ____
  7412. ¶34
  7413. Wed Jan 20, 1993 9:59:51 pm OPEN «RenameTesttemp»
  7414. ¬
  7415. ¶35
  7416. Wed Jan 20, 1993 10:00:58 pm TYPING «RenameTesttemp» 1 37 (undone)
  7417. =>inserted 94 characters:
  7418. «
  7419. This text was typed into "Renametesttemp" and then undone.
  7420. The file was saved before closing.»
  7421. ¬
  7422. ¶36
  7423. Wed Jan 20, 1993 10:00:58 pm UNDO «RenameTesttemp»
  7424. ¬
  7425. ¶37
  7426. Wed Jan 20, 1993 10:01:01 pm SAVE «RenameTesttemp»
  7427. ¬
  7428. ¶38
  7429. Wed Jan 20, 1993 10:01:02 pm CLOSE «RenameTesttemp»
  7430. ¬
  7431. ____
  7432. (Here, the undone typing in “RenameTesttemp” was turned into a
  7433. permanent activity by the following save. Only permanent undone
  7434. activities are shown as “(undone)”.
  7435.  
  7436. ____
  7437. ¶47
  7438. Wed Jan 20, 1993 10:05:22 pm OPEN «Act1»
  7439. ¬
  7440. ¶48
  7441. Wed Jan 20, 1993 10:06:13 pm TYPING «Act1» 1 1
  7442. =>inserted 70 characters:
  7443. «This text was typed into "Act1", made permanent
  7444. by the following save.»
  7445. ¬
  7446. ¶49
  7447. Wed Jan 20, 1993 10:06:14 pm SAVE «Act1»
  7448. ¬
  7449. ¶50
  7450. Wed Jan 20, 1993 10:06:17 pm CLOSE «Act1»
  7451. ¬
  7452. ____
  7453. (The typical case, activities that are made permanent by saving to
  7454. disk. There is no special indication for permanent activities, this
  7455. being the default class).
  7456.  
  7457. A permanent activity is there right now in your disk file or on-screen,
  7458. and you could, with a bit of work, undo it using the information in
  7459. the “••Recent Activities••” window—provided you can untangle it from
  7460. the effects of other permanent activities that followed it. An undone
  7461. activity was explicitly undone and the result saved, but you could redo
  7462. it in the same way you would undo a permanent activity. A temporary
  7463. activity wasn’t saved, but you could, with a bit of work, redo it using
  7464. the information in the “••Recent Activities••” window—provided you can
  7465. untangle it from the effects of other temporary activities that
  7466. preceded it. An obsolete activity no longer has a meaningful context:
  7467. the window or file in which it occurred no longer exists on screen or
  7468. disk, though if it was in a file you might have a backup version
  7469. somewhere.
  7470.  
  7471.  
  7472. §    Updated file names
  7473. When you edit a file and then use Save As to save it under a different
  7474. name, those preceding edits really apply to the file with the new name
  7475. rather than to the old name. As a typical example, when you open a new
  7476. window “Untitled-3”, type in it a bit, and then save it as
  7477. “FileCommands.c”, you will later remember the typing as being
  7478. associated with the name “FileCommands.c” rather than “Untitled-3”.
  7479. In the “••Recent Activities••” window, the file name for the typing
  7480. would be shown as “FileCommands.c”.
  7481.  
  7482. When you use Save As on a file, or Save a window for the first time,
  7483. the file name for preceding activities associated with the old name
  7484. will be updated to the new name. This updating is applied backwards
  7485. to the point where you opened or saved the affected document (or all
  7486. the way back if those activities are too old to be still recorded).
  7487.  
  7488.  
  7489.  
  7490. §    Reviewing activities
  7491. If you anticipate wanting to jump to a file that contains a particular
  7492. edit, in order to view it in context, click the “updated current
  7493. positions” while viewing the Show Activities dialog, so that the line
  7494. and characters positions shown will correspond to current actual
  7495. positions in your files (to the extent that this is possible). If you
  7496. just intend to skim through the activities without jumping to any
  7497. files, selecting the “originally recorded positions” button will speed
  7498. up the process of showing you your activities, at the expense of
  7499. showing you file positions that are uncorrected for other activities.
  7500.  
  7501. With the  “••Recent Activities••” window in front, you can use Find
  7502. to search for activities in the usual way. Here are some (rather
  7503. obvious) things you can search for:
  7504.     •    activity number, such as “¶314” (¶ is <Option><seven>)
  7505.     •    date, such as “Jan 13”
  7506.     •    time, such as “ 10:51” (put a space before the hour:minute to
  7507.         disambiguate it from minute:second)
  7508.     •    activity name, such as “START OF SESSION”
  7509.     •    file name (note including the European quotes «» sometimes helps)
  7510.     •    contents of an insert or delete
  7511.  
  7512. For activities with file positions, such as inserts and deletes and
  7513. search results, you can jump to the file and line by clicking on
  7514. the line with the file-line reference, and then picking “Go to”.
  7515. For example, given
  7516. ____
  7517. ¶60
  7518. Sat Jan 16, 1993 10:51:48 pm PASTE «hAWK_FilesandClip.c» 390 4
  7519. ...etc
  7520. ____
  7521. to open a window for hAWK_FilesandClip.c  and jump to line 390,
  7522. position 4 on the line, click somewhere on the line (for example,
  7523.  after the ‘»’…)
  7524.  
  7525.  
  7526.  
  7527. …and then pick “Go to”. For more details, see the “‘Go’ commands” chapter
  7528.  
  7529. With this use or any use of “Go to”, the file must be listed in one of
  7530. your project panes.
  7531.  
  7532. If you have selected the “updated current positions” version of your
  7533. activities, the “Go to” command will work reasonably well—in fact, it
  7534. will work as well as it possibly can. For example, if you
  7535. paste some text at line 100, and then paste in 10 lines at line 50,
  7536. then the position of the first paste will be updated from line 100 to
  7537. line 110, because that’s where you would find it if you went looking
  7538. for it now—provided it was a permanent activity. If you didn’t save
  7539. the file, thus rendering the activities temporary, then the updated
  7540. position of the first paste would still be line 100, because the
  7541. influence of the second paste was removed by virtue of not saving it.
  7542. In other words, to redo that first temporary paste, you would still
  7543. go to line 100.
  7544.  
  7545. The limit to which edit positions can be meaningfully updated shows
  7546. up for example when you delete a large chunk of text, and that deleted
  7547. chunk contained earlier inserts or deletes. If you paste some text at
  7548. line 100, and then delete lines 50 through 200, what should be the
  7549. updated position of the paste? EnterAct will show the updated position
  7550. as line 50, which, if you think about it, is the best that can be
  7551. done.The positions of obsolete activities are not updated, there being
  7552. no file or window to which the activity can be currently related.
  7553.  
  7554. §    Selective single undo
  7555. By selecting “updated current positions” when showing your activities,
  7556. you stand a very good chance of being able to identify the exact
  7557. current position of any previous insert or delete. However, the updated
  7558. position will not be terribly meaningful if the insert or delete was
  7559. later “engulfed” by a delete (for example a paste on line 100 followed
  7560. by deleting lines 50 through 200). And if the activity was an insert
  7561. that was later “nibbled at” by small inserts and deletes within the
  7562. original insert, you may find that you have to undo several activities
  7563. instead of one, or at least mentally compensate for them.
  7564.  
  7565. Once you have found the activity in the recent activities window, use
  7566. “Go to” to jump to the current position for the activity, as described
  7567. in the section above. If it still seems appropriate for undoing after
  7568. viewing it in context, the procedure for actually undoing it is, alas,
  7569. devoid of novelty:
  7570.     •    to undo an insert, identify the range of the insert in your document
  7571.         by comparing your document with the text of the insert as shown in your
  7572.         activity record; then select it and clear it out
  7573.     •    to undo a delete, copy the deleted text from your activity record
  7574.         and then paste it into your document at the current position for the
  7575.         activity.
  7576.  
  7577. If you have edited the document in question with some editor besides
  7578. EnterAct, the contents and positions of recorded activities may not
  7579. be entirely accurate. But if the edits elsewhere were small, you should
  7580. be able to compensate for them and still achieve the undo you want.
  7581.  
  7582. The recent activities window does not update as you make changes.
  7583. To force an update of positions and activities, close the window
  7584. and reopen it.
  7585.  
  7586. §    Reverting a file
  7587.  
  7588. >    Introduction
  7589. The procedure for reverting a file to an earlier form based on your
  7590. recorded activities is a bit lengthy, so step-by-step instructions are
  7591. given below. In order to revert a file you need to specify the file,
  7592. and how far back you want to go when reverting the file. The “how far
  7593. back” part is specified by an activity number from your “••Recent
  7594. Activities••” window, so you’ll need to Show Activities (with original
  7595. positions) to identify the right activity number. The actual revert
  7596. is done with the supplied hAWK program “$Multi_Undo”, and to provide
  7597. the needed input for this program you’ll save your “••Recent
  7598. Activities••” window to disk, then add it to an EnterAct project. The
  7599. file you wish reverted must also be added to the same project. The
  7600. reverted file will be presented to you in the “$tempStdOut” window when
  7601. $Multi_Undo is finished, to do with as you wish.
  7602.  
  7603. EnterAct doesn't do version control, and this reversion process, in
  7604. its present inelegant form, should be used in emergencies only.
  7605. It works, but that's all you can say for it.
  7606.  
  7607. >    Limitations
  7608. In order to revert a file (called file A below), several conditions
  7609. must be met:
  7610.     •    file A has been saved since its contents were last changed
  7611.     •    All changes to file A, from to the undo point up to the present,
  7612.         have been made with EnterAct
  7613.     •    From the undo point up to the present, no other file named "A" has
  7614.         been edited with EnterAct (ie a different disk or folder, but the same
  7615.         basic file name A)
  7616.     •    The activity corresponding to the undo point is present in
  7617.         EnterAct's "••Recent Activities••" window (it goes back up to 10,240
  7618.         activities).
  7619.     •    The entire text of each edit on file A is present in "••Recent
  7620.         Activities••": you normally won't want to check for this yourself, and
  7621.         the hAWK program “$Multi_Undo”, which you’ll be using anyway, will do
  7622.         it thoroughly for you. In general, only inserts or deletes below 64K
  7623.         characters are fully recorded, and older large edits near the beginning
  7624.         of "••Recent Activities••" may not be fully recorded if it was
  7625.         necessary to make room for newer large edits, due to the total data
  7626.         limit of 1.3Meg characters. Rule of thumb: barring a sequence of large
  7627.         edits, all of your edits will still be fully recorded. These size
  7628.         limits are only rarely encountered.
  7629.  
  7630. The reverted version of your file presented in “$tempStdOut” will not
  7631. retain any markers or illustrations from the original. Normally,
  7632. markers can be easily replaced with the Automark command. To reinstate
  7633. illustrations, you’ll need to use your resource editor to copy the
  7634. appropriate PICT’s.
  7635.  
  7636.  
  7637. >    How to revert a file
  7638. If your circumstances meet the above conditions, you can revert a file
  7639. (still called “A”) by following these steps:
  7640.     •1    Open an EnterAct project (any will do)
  7641.     •2    If necessary, add file A to it
  7642.     •3    Select "Show Activities..."; click on the "originally recorded
  7643.     positions" button; and for the number of activities to show, enter
  7644.     "10240"; and click the OK button to generate the "••Recent Activities••"
  7645.     window
  7646.     •4    Locate the oldest activity you wish undone, and note its activity
  7647.     number -- this appears just afer the "¶" beginning the activity record,
  7648.     for example "¶314"
  7649.     •5    Save "••Recent Activities••" somewhere - NOTE the name must start
  7650.     with two bullets, but is otherwise arbitrary, for example, "••RA" or
  7651.     "••For undo". The bullet character is <Option><eight>.
  7652.     •6    Add your saved version of "••Recent Activities••" to your project,
  7653.     then close the window for "••Recent Activities••" to save memory
  7654.     •7    Select both the saved version of "••Recent Activities••" and file
  7655.     A for MFS operations, by holding down the <Option> key and clicking
  7656.     on each name in the project window - a bullet • will appear beside the
  7657.     file name). These two should be the only files marked with a • in your
  7658.     project window
  7659.     •8    Call up hAWK and select the supplied program “$Multi_Undo”; the
  7660.     input option should be "MFS selected files"; use "Set Variables" to
  7661.     set the value of the variable "howFarBack" to the activity number that
  7662.     represents how far back (inclusive) you wish to undo. For example,
  7663.              howFarBack=314
  7664.     to undo from the present (the largest activity number) back to and
  7665.     including activity number 314.
  7666.     •9    Click the Run button. The undone version of file A will (eventually)
  7667.     be presented in the "$tempStdOut" window. You can continue working in
  7668.     EnterAct in the meantime.
  7669.     •10    Save "$tempStdOut" under a different name if you wish to keep the
  7670.     results (see “Preserving the undone version” just below for an
  7671.     explanation)
  7672.     •11    If there are other files you wish to restore, add them to your
  7673.     project if necessary, open your saved version of "••Recent
  7674.     Activities••" to determine how far back to undo, then close it and
  7675.     repeat steps 7-10 (especially step 10).
  7676.  
  7677. While you're waiting for $Multi_Undo to finish you should avoid editing
  7678. either file A or your saved version of "••Recent Activities••".
  7679.  
  7680. For more information on running hAWK programs see 
  7681. the “hAWK User’s Manual” supplied on disk.
  7682.  
  7683.  
  7684. >    Preserving the undone version
  7685. The “$Multi_Undo” program stops one step short of actually reverting
  7686. your file, in that the reverted version is contained in the file
  7687. “$tempStdOut” at the end, rather than immediately replacing the
  7688. contents of your file. If you decide to keep the reverted version, you
  7689. can use Save As  on “$tempStdOut” to create a permanent copy of the
  7690. reverted file. You should do this before your next hAWK or Read
  7691. Resource run, because the file “$tempStdOut”, as its name suggests,
  7692. is overwritten with every Drag_on Module run.
  7693.  
  7694. If you use Save As to replace your file A with the reverted version,
  7695. this will not be undoable, and the unreverted version will be lost.
  7696. If you’re not absolutely sure that the reverted version should replace
  7697. the unreverted version, it’s best to give the reverted version a name
  7698. name that is close to the old one (eg the reverted version of
  7699. “MyEvent.c” could be called “MyEvent2.c” or “MyEvent_r1.c” etc).
  7700.  
  7701.  
  7702. §    Turning activity recording on and off
  7703.  
  7704. >    Temporarily
  7705. When activities are being recorded you will see a menu item named
  7706. Recording activities under the Edit menu: it will change to read Not
  7707. recording activities if you select it, indicating that recording is
  7708. turned off. Selecting it again will turn recording back on. Even if
  7709. you are not recording activities, EnterAct will still open the log file
  7710. “EnterAct Recent Activities” each time you start EnterAct, creating
  7711. it if it is not found. And you will still be able to Show Activities.
  7712.  
  7713. Turning activity recording off temporarily is rarely useful. However,
  7714. you might consider it if you are about to perform a number of trivial
  7715. changes, or very large edits that you don’t need recorded, and want
  7716. to preserve the current record of your activities as much as possible.
  7717. But if you are aware that vitally important data exists only in your
  7718. recorded activities, it would be better to Show Activities and Save
  7719. the resulting activity list to disk, to avoid losing the data as older
  7720. activities are dropped from the log file.
  7721.  
  7722.  
  7723. >    More permanently
  7724. The “master switch” for EnterAct’s activity recording is in the Options
  7725. dialog (under the Edit menu). 
  7726.  
  7727. You may wish to forego the recording of your activities if you don’t
  7728. have enough disk space available to hold the log file (2.1Meg), or if
  7729. your hard disk makes so much noise that you can’t work when it’s
  7730. active.  To turn off activity recording, and also instruct EnterAct
  7731. not to look for or create the “EnterAct Recent Activities” log file,
  7732. uncheck the “Save activities to disk” option in the Options dialog and
  7733. click the OK button: as you do so, the icon of the log file will be
  7734. crossed out, indicating that the file will no longer be needed or used.
  7735. You may then dispose of the log file if you wish, and EnterAct will
  7736. not complain.
  7737.  
  7738.  
  7739.  
  7740.  
  7741.  
  7742.  
  7743.  
  7744.  
  7745.  
  7746.  
  7747.  
  7748.  
  7749.  
  7750.  
  7751.  
  7752.  
  7753.  
  7754.  
  7755.  
  7756.  
  7757.  
  7758.  
  7759.  
  7760. To reactivate activity recording, check the “Save activities to disk”
  7761. option in the Options dialog and click OK. A log file will immediately
  7762. be created if one does not exist at the time. If the log file exists,
  7763. recording will pick up again with no loss of previously recorded
  7764. activities.
  7765.  
  7766.  
  7767. -    -    -    -    -    -    -    -    -    -    -    -
  7768. “Index” commands
  7769. -    -    -    -    -    -    -    -    -    -    -    -
  7770.  
  7771. PLEASE NOTE the index commands "Functions", "Cross-Reference",
  7772. "Potential Locals" and "Check Prototypes" are intended for use
  7773. with C code only (not C++ or Java).
  7774.  
  7775.  
  7776.  
  7777.  
  7778.  
  7779.  
  7780.  
  7781.  
  7782.  
  7783.  
  7784.  
  7785.  
  7786.  
  7787.  
  7788.  
  7789.  
  7790.  
  7791.  
  7792.  
  7793.  
  7794.  
  7795.  
  7796.  
  7797.  
  7798.  
  7799.  
  7800.  
  7801.  
  7802.  
  7803.  
  7804.  
  7805.  
  7806. The “Index” commands under the EnterAct menu generate a variety of
  7807. reports on your source code. With all except the Potential Locals
  7808. and Check Prototypes command, set up a multi-file selection first
  7809. to serve as input for the command. Potential Locals takes a function
  7810. body with parameters as input. Check Prototypes looks at all of
  7811. the function definitions and prototypes in your entire project.
  7812. All output from these commands is to $tempStdOut.
  7813.  
  7814. Functions… builds a list of functions in your selected files: it can
  7815. list functions defined in the files together with sublists of the
  7816. functions that each defined function calls, or conversely you can have
  7817. a list of all the functions called in your source code, together with
  7818. sublists showing which functions call them.
  7819.  
  7820. Cross-Reference… generates a cross-reference listing: you can specify
  7821. the types of term (function, struct, variable etc) to include, the
  7822. specific terms to look for (your current dictionary), and the files
  7823. to look in (your current multi-file selection). Supporting doc files
  7824. in your rightmost project pane can be included in the cross-reference.
  7825. You can also specify a list of common words (such as Handle) to skip
  7826. for cross-reference purposes.
  7827.  
  7828. #Includes and Marker Names generate lists of system or user headers,
  7829. and marker names in a variety of formats, in your selected files.
  7830.  
  7831. Potential Locals classifies and lists all terms in a function. Just
  7832. before this command, select the entire body of the function and the
  7833. parameters (ie from the opening ‘(’ of the parameters to the closing
  7834. ‘}’ of the function, inclusive). In the resulting list, names that have
  7835. no definition and are not parameters, and hence are probably local
  7836. variables, are listed first. The number of times each name was used
  7837. is also listed, and by comparing this list with your original function
  7838. you can quickly declare all necessary variables or eliminate
  7839. unnecessary declarations, and also spot spelling mistakes.
  7840.  
  7841. Standard Metrics issues counts of lines and characters in selected
  7842. files, and also shows character frequencies.
  7843.  
  7844. Check Prototypes is rather primitive, catching only a difference
  7845. in the number of parameters to a function. No need to bullet any
  7846. files, just bring your dictionary up to date beforehand. It's intended
  7847. for use with C source only, not C++ or Java.
  7848.  
  7849.  
  7850. §    Functions…
  7851. For use with C source only.
  7852.  
  7853.  
  7854.  
  7855.  
  7856.  
  7857.  
  7858.  
  7859.  
  7860.  
  7861.  
  7862.  
  7863.  
  7864.  
  7865.  
  7866. This command can be used to build a “skeleton” for selected source
  7867. files, a bare list of functions defined together with the functions
  7868. they call. It also works in reverse, and can be used to list all
  7869. functions that are called, together with sublists of the functions that
  7870. call them. Input is taken from your list of files selected for
  7871. multi-file operations (use the Find dialog buttons, or <Option>click
  7872. in the project window, see the “Search” chapter). Only files in the
  7873. left and middle project window panes will be looked at, and any files
  7874. you select in the right (documentation) pane will be ignored. You’ll
  7875. see results in “$tempStdOut”: if you decide you want to save the
  7876. results permanently, use Save As to save this document under a new name
  7877. of your choice, since the contents of $tempStdOut are overwritten by
  7878. every Index command or Drag_on Module run.
  7879.  
  7880. For proper results, your dictionary should be reasonably up to date
  7881. before using this command. In particular, your dictionary should
  7882. contain entries for all functions that you wish to see listed. For
  7883. example, in order for toolbox functions to show up in the listing
  7884. you’ll need to add the appropriate toolbox headers to your project and
  7885. update your dictionary.
  7886.  
  7887. When you select “with calls” in the Functions dialog, the main list
  7888. in the result will consist of functions defined in your list of source
  7889. files. Indented under each defined function will be a list of functions
  7890. called by the defined function. If you select “as defined” then
  7891. function definitions will be listed in the order encountered in your
  7892. source files, with a comment containing the file name beginning each
  7893. list for each file:
  7894.  
  7895.  
  7896.  
  7897.  
  7898.  
  7899.  
  7900.  
  7901.  
  7902.  
  7903.  
  7904.  
  7905.  
  7906.  
  7907.  
  7908.  
  7909.  
  7910.  
  7911.  
  7912.  
  7913.  
  7914.  
  7915.  
  7916.  
  7917.  
  7918.  
  7919.  
  7920.  
  7921. If you select "sorted” then all of the function definitions from all
  7922. files will be sorted alphabetically. In this case you can select
  7923. “include file locations” to list the defining file for each function:
  7924.  
  7925.  
  7926.  
  7927.  
  7928.  
  7929.  
  7930.  
  7931.  
  7932.  
  7933.  
  7934.  
  7935.  
  7936.  
  7937.  
  7938.  
  7939.  
  7940.  
  7941.  
  7942.  
  7943.  
  7944.  
  7945.  
  7946.  
  7947.  
  7948.  
  7949.  
  7950.  
  7951. If you select “with callers” the resulting list will show all functions
  7952. that are called in your source code, with an indented sublist for each
  7953. naming the functions that call it. Here also, if you select “include
  7954. file locations” then the defining file name will be listed with each
  7955. function name.
  7956.  
  7957.  
  7958.  
  7959.  
  7960.  
  7961.  
  7962.  
  7963.  
  7964.  
  7965.  
  7966.  
  7967.  
  7968.  
  7969.  
  7970.  
  7971.  
  7972.  
  7973.  
  7974.  
  7975.  
  7976.  
  7977.  
  7978.  
  7979.  
  7980.  
  7981.  
  7982.  
  7983. With any function name, you can jump to the definition for it by
  7984. <Option> double-clicking on the name. File names in the listings are
  7985. enclosed in «» quotes: to open a file, click anywhere on the line
  7986. containing the file name and issue a “Go to”.
  7987.  
  7988.  
  7989. §    Cross-Reference…
  7990. For use with C source only.
  7991.  
  7992.  
  7993.  
  7994.  
  7995.  
  7996.  
  7997.  
  7998.  
  7999.  
  8000.  
  8001.  
  8002.  
  8003.  
  8004.  
  8005.  
  8006.  
  8007.  
  8008.  
  8009.  
  8010.  
  8011.  
  8012.  
  8013.  
  8014.  
  8015.  
  8016.  
  8017.  
  8018.  
  8019.  
  8020.  
  8021.  
  8022.  
  8023.  
  8024. The Cross-Reference command generates a cross-reference for all term
  8025. types you select, in all files selected for multi-file operations.
  8026. Names are listed in alphabetical order, with a sublist for each name
  8027. listing file name and line number for each instance, and optionally
  8028. the name of the function containing the instance. Only names that are
  8029. defined in your current project dictionary will be included in the
  8030. listing. Note that you can cross-reference supporting documents with
  8031. this command, by putting a bullet (•) beside the name of each
  8032. supporting document. The “include containing function names” option
  8033. will be ignored for support docs.
  8034.  
  8035. To generate a cross-reference just for names that are defined in
  8036. certain files, rather than all names defined in your current dictionary
  8037.     •    make a new project, and add to it only those source and header files
  8038.         which contain functions, variables, structs etc to be included in the
  8039.         cross-reference
  8040.     •    use Update Dictionary to build a dictionary for just those names
  8041.     •    add any additional files to be cross-referenced to your project
  8042.     •    place bullets (•) beside the names of all files you want to
  8043.         cross-reference
  8044.     •    select Cross-Reference
  8045.     •    optionally specify a file containing a list of common words to skip,
  8046.         with the “Skip words in…” button
  8047.     •    specify the term types (function, variable etc) to be included in
  8048.         the cross-reference, or click the “All types” button
  8049.     •    click OK and your desired list will appear in the $tempStdOut window
  8050.  
  8051. Normally your current project dictionary will be the appropriate one
  8052. to use for cross-referencing, and you won’t need to make a new project
  8053. just for this purpose.
  8054.  
  8055. As with all Index commands, use Save As to save $tempStdOut under a
  8056. different name if you decide to keep the results—$tempStdOut will be
  8057. overwritten by your next Index command or hAWK run.
  8058.  
  8059. The “Skip words in…” button in the Cross-Reference dialog allows you
  8060. to specify a list of words to skip, typically common names such as OK,
  8061. Handle, DialogPtr that you aren’t interested in. The names in the file
  8062. can appear in any order, and can be separated from one another by
  8063. spaces or <Return>’s. The file “Skip for XRef” which comes with
  8064. EnterAct contains a starter list. You’ll find it in the “hAWK Programs”
  8065. folder, which is inside the “Drag_on Modules” folder inside your
  8066. development folder.
  8067.  
  8068.  
  8069.  
  8070.  
  8071.  
  8072.  
  8073.  
  8074.  
  8075.  
  8076.  
  8077.  
  8078.  
  8079.  
  8080.  
  8081.  
  8082.  
  8083.  
  8084.  
  8085.  
  8086.  
  8087.  
  8088.  
  8089.  
  8090.  
  8091.  
  8092.  
  8093.  
  8094.  
  8095.  
  8096.  
  8097.  
  8098.  
  8099.  
  8100.  
  8101.  
  8102.  
  8103.  
  8104.  
  8105.  
  8106. To cancel the use of a skip-list, click the “Skip none” button.
  8107. When you select “include containing function names” the name of the
  8108. function, if any, containing each reference will be shown to the right
  8109. of each reference. Names which occur outside of a function body,
  8110. including all names encountered in support documents, will not have
  8111. a containing function listed.
  8112.  
  8113. The format of each reference such as
  8114. ____
  8115.     «AssocArray.c»        260        SetArrayValue
  8116. ____
  8117.  is «file name» line-number containing-function (if any). To go to a
  8118.  particular reference, click on the reference line and use “Go to”. To
  8119.  jump to the definition of a containing function, <Option> double-click
  8120.  on its name.
  8121.  
  8122.  
  8123. §    #Includes…
  8124.  
  8125.  
  8126.  
  8127.  
  8128.  
  8129.  
  8130.  
  8131.  
  8132.  
  8133.  
  8134.  
  8135.  
  8136.  
  8137.  
  8138.  
  8139.  
  8140.  
  8141.  
  8142.  
  8143.  
  8144.  
  8145.  
  8146.  
  8147.  
  8148.  
  8149. To list header files that are included in one or more source or header
  8150. files:
  8151.     •    select the source and header files for multi-file operations
  8152.     •    select the #Includes… command
  8153.     •    pick either system headers with the <headers> button, or
  8154.         project-specific headers with the “headers” button, or both
  8155.     •    click OK, and the list will appear in the $tempStdOut window
  8156.     •    use Save As on $tempStdOut to make a permanent copy of the results.
  8157.  
  8158. Included file names are listed in the order encountered, together with
  8159. line number.
  8160.  
  8161.  
  8162. §    Marker Names…
  8163.  
  8164.  
  8165.  
  8166.  
  8167.  
  8168.  
  8169.  
  8170.  
  8171.  
  8172.  
  8173.  
  8174.  
  8175.  
  8176.  
  8177.  
  8178.  
  8179.  
  8180.  
  8181.  
  8182.  
  8183.  
  8184.  
  8185.  
  8186.  
  8187.  
  8188.  
  8189.  
  8190.  
  8191. To list the names of all markers in one or more files:
  8192.     •    select the files (any panes) for multi-file operations
  8193.     •    select the Marker Names… command
  8194.     •    pick your preferred format for the names
  8195.     •    click OK, and the list will appear in the $tempStdOut window
  8196.     •    use Save As on $tempStdOut to make a permanent copy of the results.
  8197.  
  8198. The «file-name»«marker-name» format is useful for establishing “go to”
  8199. links, as explained in the “‘Go’ commands” chapter. The other two
  8200. formats can also be used as “go to” links, but work only within the
  8201. file that contains the marker.
  8202.  
  8203. EnterAct's default behavior is to NOT save marks with source or
  8204. header files, so there will normally be no marks listed for these
  8205. files. In practise you will probably not need special  “go to” links
  8206. for functions or structs anyway, since <Option>double-clicking
  8207. on the name anywhere will take you to the definition. “Go to” links
  8208. are intended mainly for establishing hyperlinks to documentation
  8209. files (this manual is already redundant enuff, so please see chapter 17
  8210. for details on creating and using «file-name»«marker-name» links).
  8211.  
  8212. §    Potential Locals
  8213. For use with C source only.
  8214.  
  8215.  
  8216.  
  8217.  
  8218.  
  8219.  
  8220.  
  8221.  
  8222.  
  8223.  
  8224.  
  8225.  
  8226.  
  8227.  
  8228.  
  8229.  
  8230.  
  8231.  
  8232.  
  8233.  
  8234.  
  8235.  
  8236.  
  8237.  
  8238.  
  8239.  
  8240.  
  8241.  
  8242.  
  8243.  
  8244.  
  8245.  
  8246.  
  8247.  
  8248.  
  8249.  
  8250.  
  8251.  
  8252.  
  8253.  
  8254.  
  8255. This command helps with the declaration of local variables. To use it,
  8256. first select the parameters and body of a function, from the opening
  8257. parenthesis of the parameters to the closing curly brace of the
  8258. function body, inclusive, as shown above left. Then select Potential
  8259. Locals:results will be shown in $tempStdOut.
  8260.  
  8261. Names are shown three per line, each followed by the number of times
  8262. the name was encountered in the function. The first list, “These look
  8263. most like locals:”, consists of those names seen in the function which
  8264. have no entries in your current dictionary, and hence they are the best
  8265. candidates to be local variables. Note, though, that they could also
  8266. be goto labels, or names that for some reason are not defined in your
  8267. dictionary. Names in this list with a frequency of 1 bear a close
  8268. look—often they have been used but not declared, or declared but not
  8269. used, or the name has a typo. Names in the other lists might also need
  8270. declaration as local variables, if you have used the same name for a
  8271. local and something else (such as a global variable, typically).
  8272.  
  8273.  
  8274. §    Standard Metrics
  8275. This command reports the total lines and characters in each of your
  8276. files selected for multi-file operations, followed by a C-style array
  8277. listing the number of times each character was seen. Comment characters
  8278. and lines are included in the totals, but blank lines at the end of
  8279. a file aren’t counted as lines.
  8280.  
  8281.  
  8282.  
  8283.  
  8284.  
  8285.  
  8286.  
  8287.  
  8288.  
  8289.  
  8290.  
  8291.  
  8292.  
  8293.  
  8294.  
  8295.  
  8296.  
  8297.  
  8298.  
  8299.  
  8300.  
  8301.  
  8302.  
  8303.  
  8304.  
  8305.  
  8306. §    Check Prototypes
  8307. For use with C source only.
  8308.  
  8309. This command checks all of the function definitions and
  8310. prototypes in your project dictionary, checking ONLY the
  8311. number of parameters for each function. It reports the
  8312. names of any functions that are declared with different
  8313. numbers of parameters. Before calling this command, you
  8314. should bring your dictionary up to date with Update Dictionary
  8315. for best results.
  8316.  
  8317. There is no need to select any files for multi-file operations
  8318. when using this command. You just need a project open with
  8319. a built dictionary.
  8320.  
  8321. This is a primitive version, and catches only differences in the
  8322. NUMBER of parameters to a function. And it's only for C files, not
  8323. C++ or Java. Don't trust it to validate prototypes, use it only
  8324. to spot the particular problem of the same-named
  8325. C function having a different number of parameters in
  8326. variant declarations. This typically happens when you change
  8327. the definition of a function and forget to change a prototype
  8328. for it in a different file.
  8329.  
  8330. If no prototypes are shown in stdout, your function definitions
  8331. and declarations all had a consistent number of parameters.
  8332. Or arguments, if you prefer. I won't argue.
  8333.  
  8334. -    -    -    -    -    -    -    -    -    -    -    -
  8335. Some thoughts on using EnterAct
  8336. -    -    -    -    -    -    -    -    -    -    -    -
  8337. (Worth mentioning again, EnterAct can be used as just a
  8338. "definition viewer" to help out other editors -- see
  8339. the end of "Lookup", chapter 10)
  8340.  
  8341. (As of September 95, the advice below about how to avoid lookup
  8342. delays and minimize memory use is sounding a bit dated; however,
  8343. it's still true that smaller projects are easier to manage.)
  8344.  
  8345. §    Projects are cheap
  8346. EnterAct projects are quick and easy to create, the only real penalty
  8347. being the amount of disk space used. While an EnterAct project can be
  8348. truly enormous and still be usable, lookup will be faster and more
  8349. appropriate if you tailor your project to the problem at hand. As an
  8350. extreme example, here’s a generic project that would be perfectly
  8351. suitable for developing file–handling functions:
  8352.  
  8353.  
  8354.  
  8355.  
  8356.  
  8357.  
  8358.  
  8359.  
  8360.  
  8361.  
  8362. Lookup in this size project will always be instantaneous no matter how
  8363. bad your spelling, and lookup for your terms will never be confused
  8364. by accidental matches against terms in files that you don’t need
  8365. reference to. While accidental matches are not common, the speed of
  8366. lookup when your spelling is not exact does depend directly on the size
  8367. of your dictionary.
  8368.  
  8369. At the other extreme, you can create projects with files from more
  8370. that one application/driver etc. This can be very handy for comparing
  8371. different versions or different approaches to a problem. In practise,
  8372. the main penalty comes when you want to jump to a particular
  8373. definition, and there's more than one: to choose the one you want,
  8374. you have to press <Enter> to look it up and then <Option>double-click
  8375. in the lookup window.
  8376.  
  8377. The rule of thumb then is that an EnterAct project can consist of
  8378. whatever files you want, but performance will be better if you don’t
  8379. add files that you don’t need. There is a tradeoff between having
  8380. absolutely everything of potential interest in a large, complicated
  8381. project, and having several smaller but better–performing projects.
  8382.  
  8383. For ultra-compact project backup, in the event that some of your
  8384. projects are tedious to create:
  8385.     •    select all of the files in your project for multi-file ops, by
  8386.     clicking the "All" button in the Find dialog
  8387.     •    select hAWK from the EnterAct menu, and select and run
  8388.     the program "$EchoFullPathNames"
  8389.     •    use Save As on the resulting stdout window to save your
  8390.     list of project files
  8391.     •    to recreate your project: create a New Project; hold
  8392.     down the <Shift> key while selecting "Add Files..." (the menu
  8393.     text will read "Add Files from List...") and select your text
  8394.     file of full path names in the subsequent Open dialog; and
  8395.     bring your dictionary up to date after the files are added.
  8396.  
  8397. §    Learning from or reviewing code
  8398. If your purpose is to explore rather than create, then you won’t be
  8399. typing in many incorrect spellings. Lookup when spelling is correct
  8400. is always instant, which is the case if you’re just reading through
  8401. code and looking up terms in the code as you go. In this case the only
  8402. restrictions on the size of the project are the amount of disk space
  8403. and RAM needed, and you can add absolutely all files related to the
  8404. application without slowing down the lookup.
  8405.  
  8406. (Strictly speaking, lookup is instant only for terms with entries
  8407. in your dictionary. Specifically, struct and class member names
  8408. are not separately entered in your dictionary, and it can take
  8409. a second or more for the AutoLook window to pull up a definition
  8410. that contains the member name. Sorry, there's no plan to speed
  8411. up member lookup. Member lookup won't hang you up, it will just
  8412. be stopped if you start typing or mousing around during the search.)
  8413.  
  8414. §    On documenting your work
  8415. There is little in this manual on the topic of documentation, primarily
  8416. because it’s up to you how, and how much, you document your work in
  8417. separate files. But it’s worth mentioning that EnterAct has a variety
  8418. of features to help you create and maintain your documentation. Here’s
  8419. a list:
  8420.     •    documentation files can be added to the rightmost pane of your
  8421.         project, for regular double-click access just like source and header
  8422.         files
  8423.     •    <Option> double-click or Find Definition can be used on any term
  8424.         that appears in your documentation to jump to its definition (provided
  8425.         of course that your dictionary is reasonably up-to-date)
  8426.     •    the AutoLook window will instantly update to display definitions
  8427.         of terms in your documentation (double-click on the term or click just
  8428.         after it). And clicking after a term and pressing the <Enter> key will
  8429.         produce a more persistent separate lookup window
  8430.     •    your own notes on various programming topics can be “disguised” as
  8431.         C terms, and in this form they can be built into your project
  8432.         dictionary for instant retrieval to the AutoLook window or a separate
  8433.         lookup window wherever the name of the note appears (see “Looking up
  8434.         your notes” in the “Lookup” chapter)
  8435.     •    “Go to” accepts file name followed by marker name, as explained in
  8436.         the “‘Go’ commands” chapter. These look like
  8437.         /* See «MY OOP Notes» «Static variables» */
  8438.         and the text for them can be generated by picking the marker from
  8439.         the popup menu in the document where it is defined while holding down
  8440.         the <Shift> key as well as the usual <Option> or <Command> key. The
  8441.         link location is maintained as you edit, since the marker’s location
  8442.         is maintained, and if the file and marker names are in «» quotes
  8443.         they can be abbreviated or even slightly incorrect and still work.
  8444.     •    “Go to” also accepts file-name and/or line-number selections. Text
  8445.         for this style of “go to” link is generated by the Show Activities
  8446.         command, and by a variety of supplied hAWK programs. For an example
  8447.         of line numbers used to index a document, see the “Active Index” at
  8448.         the bottom of the “hAWK User’s Manual” on disk 2.
  8449.     •    Reformat Selection can be used to even up the lines in one or more
  8450.         paragraphs of your documentation
  8451.     •    if you have any relevant PICT files, you can add them to your
  8452.         project for quick access. And “Go to” accepts PICT file names. You can
  8453.         also add one or more PICT’s as illustrations in a TEXT document (see
  8454.         “Illustrating your text” in the “Editing” chapter).
  8455.     •    the hAWK program "$CompareFiles" can be run on any two of your
  8456.         project files to list differences.
  8457.  
  8458. EnterAct can track and link all of your supporting documentation. If
  8459. you develop naming conventions for your documents, and make use of some
  8460. of EnterAct’s linking power, you should find it’s a lot easier to keep
  8461. track of things. References will be just a double-click or “Go to” away,
  8462. which beats shuffling through a stack of papers or calling up an
  8463. accessory outliner all to heck (pardon the enthusiasm).
  8464.  
  8465. -    -    -    -    -    -    -    -    -    -    -    -
  8466. If there’s a problem
  8467. -    -    -    -    -    -    -    -    -    -    -    -
  8468. §    Out of memory
  8469. If you run out of memory while trying to do something, you’ll see an
  8470. Alert saying “Out of memory. Please close up and try again when things
  8471. are less busy.” or the equivalent. Open windows take up memory that
  8472. you can free by closing the window The project especially can
  8473. take a lot of memory (Megabytes), since the entire dictionary
  8474. associated with it is kept in memory.
  8475.  
  8476. If you encounter frequent “Out of memory” messages, the least
  8477. inconvenient but most expensive cure is to allow more memory for
  8478. EnterAct, which may involve buying some chips. However, you can
  8479. often free up a considerable amount of memory by removing relatively
  8480. unneeded files from your project. The rough rule is that your project
  8481. dictionary will take up in memory about one–half of the disk space
  8482. used by all .c and .h files in the project (a better estimate, 16% of
  8483. source files plus 120% of header files). If you don’t need lookup for any
  8484. of the terms in a .c or .h file, removing it from your project will free
  8485. up some memory. Note that plain text files in the rightmost pane do
  8486. not greatly affect memory used, since they are not incorporated into
  8487. the dictionary.
  8488.  
  8489. To see how much memory is free at any time, select Show Activities from
  8490. the Edit menu. At the bottom of the resulting dialog you will see the
  8491. amount of memory currently available. Or you can use "About This
  8492. Macintosh..." in the Finder, turn Balloon Help on, and point your mouse
  8493. at EnterAct in the dialog.
  8494.  
  8495. For a guide to estimating memory needs and trimming unneeded files from
  8496. your project, see the file “EnterAct memory needs”.
  8497.  
  8498.  
  8499. §    Dictionary problems
  8500. >    Missing dictionary entries
  8501. In rare cases, an error in your source may lead to a term not being
  8502. recorded in your dictionary, with no message. An example is
  8503. ____
  8504.     int x        /* missing semicolon */
  8505.     long y;
  8506. ____
  8507. for which EnterAct would record only the “y”, missing the “x”. This
  8508. is the one time that EnterAct’s tolerance of errors can be a nuisance,
  8509. but if you can remember where the term is defined then visual
  8510. inspection should reveal the error, typically a missing semicolon or
  8511. a missing or misspelled keyword. If you can’t remember where the term
  8512. is defined, and you really want lookup to be available for it, then
  8513. the one sure cure is to switch to THINK C and Compile or Check Syntax
  8514. until you spot and fix the bug.
  8515.  
  8516.  
  8517. >    Trouble building your dictionary
  8518. If the dictionary–builder trips over a bug in your code and you can’t
  8519. spot the problem after reading this section and examining your code,
  8520. your next best course of action is to switch to THINK C and compile
  8521. the offending file. If you call for technical support and your code
  8522. is not compilable, there is only a small chance we can help, since the
  8523. possibilities would be too open–ended. Look on the bright side, you’ll
  8524. have to compile your code sooner or later anyway. 
  8525.  
  8526. EnterAct sets moderately strict standards for the part of your code
  8527. that is outside of a function, struct, or union body. However, code
  8528. that is inside of a function, struct, or union body is primarily
  8529. checked only for proper balance in a few key delimiters, typically {},
  8530. (), and /* */. As a result, almost all of your first–draft errors will
  8531. be simply ignored. Some errors outside of a body can be compensated
  8532. for, and the remainder that do trigger a complaint from the
  8533. dictionary–builder will almost always be fairly obvious.
  8534.  
  8535. Here follows a complete list of the messages you might see after
  8536. selecting Update Dictionary or Update For Front File Only. 
  8537.  
  8538. ____
  8539. "Statement too complex to deal with all at once. Any chance you could
  8540. simplify?"
  8541. ____
  8542. This message should be rather rare. You would have to nest brackets
  8543. more than 200 deep, or have more than 256 enum constants in a single
  8544. enum in order to produce it. I’m not giving an example! The cure would
  8545. be to reduce the number of brackets in your deeply–nested construction,
  8546. or split a monstrous enum into two parts.
  8547.  
  8548. ____
  8549. "Typedef cannot have an init. One or the other has to go."
  8550.     typedef int SHORT = 7;
  8551. ____
  8552. This should prove rare. “typedef” essentially creates a new keyword,
  8553. and you can no more initialize it than you could initialize “int”
  8554. itself. Apologies for stating the obvious.
  8555.  
  8556. ____
  8557. "Illegal word or punctuation after struct or union."
  8558.     struct int myStruct {...     /* int */
  8559.     struct /myStruct {...        /* the '/' */
  8560.     struct myStruct (...}        /* wrong bracket */
  8561. ____
  8562. Something between “struct” or “union” and the opening left brace (if
  8563. any) of the body doesn’t belong. Or, you may have neglected to type
  8564. in a name for the struct or union.
  8565.  
  8566. ____
  8567. "Illegal word or punctuation after enum."
  8568.     enum Numbers int {...        /* int */
  8569.     enum /Numbers {...            /* the '/' */
  8570.     enum Numbers {one two three}; /* missing commas */
  8571.     enum Numbers {one, two; three}; /* that first semicolon */
  8572. ____
  8573. Includes all the sorts of errors for a “struct” or “union”, and also
  8574. any error inside the body of the enum where the enum constants are
  8575. listed. EnterAct does not record any terms inside a struct or union,
  8576. but does record all enum constants, hence checking for an enum is more
  8577. strict. Some errors (such as an extra comma) can be shrugged off, but
  8578. most others will trigger this message.
  8579.  
  8580. ____
  8581. "#if has no matching #endif, #else, or #elif."
  8582. ____
  8583. I’m afraid you’re on your own tracking this error down, since it could
  8584. be anywhere in the file after the position shown. It could be due to
  8585. a misspelling, such as #eles, or the necessary “if–ender” could be
  8586. missing altogether.
  8587.  
  8588. ____
  8589. "Function(?) has no name."
  8590.     long    (int x, char *tPtr);
  8591. ____
  8592. So, give the poor function a name.
  8593.  
  8594. ____
  8595. "Pascal must be followed by a function."
  8596. ____
  8597. “Pascal” or “pascal” indicates that a function passes arguments and
  8598. returns a value according to Pascal rather than C conventions. For more
  8599. on this topic, see your THINK C manual.
  8600.  
  8601. ____
  8602. "Couldn't find end of initialization."
  8603.     struct MyStruct {int x; long y} instance = {4, 7L;
  8604. ____
  8605. Typically this is caused by a missing or extra '}', as in the above
  8606. example. It could also be caused by a missing semicolon.
  8607.  
  8608. ____
  8609. "Unbalanced statement. Use the Balance command right after OK'ing this
  8610. alert to diagnose the problem."
  8611. ____
  8612. Since the Balance command checks all delimiters and shows you at least
  8613. one end of an unbalanced construction, finding the typo that caused
  8614. the lack of balance is usually straightforward. Selecting Balance a
  8615. second time can be useful—after the second Balance either you’ll be
  8616. shown a mismatch for the first delimiter or you’ll hear a beep
  8617. indicating that the other end is completely missing.
  8618.  
  8619. ____
  8620. "Unbalanced or nested comment. Use the Balance command right after
  8621. OK'ing this alert to diagnose the problem."
  8622. ____
  8623. EnterAct’s comment checking while dictionary–building (and balancing)
  8624. is even stricter than most compilers. For details, see the “Nested and
  8625. bad comments” section in the “Balance” chapter. As a byproduct of
  8626. dictionary–building, all source files in your project will be
  8627. thoroughly checked for comment errors.
  8628.  
  8629. If the problem is due to consecutive comment starts, and you want to
  8630. keep them because that’s the way you do things, select Options from
  8631. the Edit menu and uncheck the “Detect nested comment starts” check box.
  8632. This will partially disable EnterAct’s ability to trap comment
  8633. problems, both when building your dictionary and when balancing.
  8634.  
  8635. ____
  8636. "Lack of balance in parentheses (). Use the Balance command right after
  8637. OK'ing this alert to diagnose the problem."
  8638. ____
  8639. See above, Unbalanced statement....
  8640.  
  8641. ____
  8642. "Unbalanced single or double quotes. Use the Balance command right after
  8643. OK'ing this alert to diagnose the problem."
  8644. ____
  8645. See above, Unbalanced statement....
  8646.  
  8647. ____
  8648. "Unbalanced square brackets []. Use the Balance command right after
  8649. OK'ing this alert to diagnose the problem."
  8650. ____
  8651. See above, Unbalanced statement....
  8652.  
  8653. ____
  8654. "Left curly brace { is not preceded by struct, union, enum, =, or
  8655. function definition."
  8656.     typedef stork MyStruct {int x; long y};/* stork?struct? */
  8657.     long ShouldBeFunction{int x, long y); /* '{' vs '(' */
  8658. ____
  8659. Either the '{' should be something else, such as a '(', or a keyword
  8660. just before the '{' is missing or badly misspelled. EnterAct can handle
  8661. some typo’s, such as typdef sturct... but at some point (such as
  8662. twerpdeaf stork) has to give up and complain.
  8663.  
  8664. ____
  8665. "Colon must signal class name, method name, or low-memory global."
  8666. ____
  8667. Note this exludes some uses of the colon which are irrelevant for
  8668. dictionary–building, such as bit fields and any usage inside a function
  8669. body.
  8670.  
  8671. ____
  8672. "Something is wrong at or near the position shown. Sorry,
  8673. if you can't fix the problem please email tech support."
  8674. ____
  8675. A Shakespearean sonnet will trigger this message. In general, the error
  8676. lies outside of EnterAct’s area of competence. Check for typo’s at or
  8677. near the position shown in the file. This message corresponds to the
  8678. “Syntax error” message that compilers issue when they give up and don’t
  8679. have a clue what’s going on.
  8680.  
  8681. My favourite way to generate this error is to accidentally add a junk
  8682. file with a name ending in .c or .h to a project. A reminder, Add All
  8683. In Folder inhales every text file in a folder.
  8684.  
  8685. This message can also be triggered by a preprocessor conditional that's
  8686. too tough for EnterAct to handle without your help -- see
  8687. "DON’T GIVE UP" near line 108 in this file, and also "Source code
  8688. restrictions", chapter 7, for the details. The symptom here is often
  8689. that the indicated error position is within a function body, an unusual
  8690. case because EnterAct's parser does almost nothing with function
  8691. bodies except check them for balance -- this means the parser ran
  8692. past the start of the function without seeing it. If you spot the usage
  8693. of a macro just above the function, and the usage does not end with
  8694. a semicolon, try entering the name of the macro in the "Macro's to
  8695. skip..." dialog. This usually fixes the problem.
  8696.  
  8697. ____
  8698. "Function body was expected but not found at the position shown."
  8699. ____
  8700. This typically results from a missing left brace '{' at the start of
  8701. a function. Rarely, it can be caused by an excess semicolon in an
  8702. “old–fashioned” style function definition, between the list of
  8703. arguments in round brackets and the start of the function body, eg:
  8704. ____
  8705.     int myFunc(x,y)
  8706.     int x;
  8707.     long y;; /* extra semicolon */
  8708.     {...}
  8709. ____
  8710. The dictionary–builder counts up your arguments, and won’t allow more
  8711. semicolons than you have arguments.
  8712.  
  8713.  
  8714. §    Lookup problems
  8715. For background, here’s a list of common errors that may throw regular
  8716. lookup off:
  8717.     •1    using a synonym
  8718.     •2    full spelling when a nonstandard abbreviation is wanted
  8719.     •3    use of an abbreviation when fuller spelling is wanted
  8720.     •4    full spelling when a standard abbreviation is wanted
  8721.     •5    case error
  8722.     •6    permutation of the words in a name
  8723.     •7    typo
  8724.     •8    spurious extra character
  8725.     •9    homonym (sounds the same, spelled differently)
  8726.     •10    missing definition, due to an error in the source or source file
  8727.             not included etc
  8728.  
  8729. Regular lookup can compensate for the more popular single instances
  8730. of 1-3 above with the lookup table of alternate spellings that you’ll
  8731. find in EnterAct’s 'TEXT' 1000 resource. Single instances of 4-5 are
  8732. thoroughly checked (see next page for the definition of a standard
  8733. abbreviation). An instance of error 6 is also caught, provided there
  8734. are at most four words making up the name. For all other errors (7-10,
  8735. or combinations of errors) EnterAct exhaustively checks what you’ve
  8736. typed against all dictionary entries, totalling up runs of matching
  8737. characters and showing the best matches. If the definition is just
  8738. plain missing, there’s not much that EnterAct can do to help.
  8739.  
  8740. “Sounds like” lookup is extremely error-tolerant, including being
  8741. case-insensitive, at the expense of ignoring some of the information
  8742. (mainly vowels and case) in what you type. It does do the fast checks
  8743. for errors 1-6 above, in the same way as regular lookup. On average
  8744. it’s less accurate than regular lookup, but useful as a last resort.
  8745.  
  8746. Reverse lookup tolerates only case errors, being case-insensitive;
  8747. otherwise, your spelling must be exact (current machines are too slow
  8748. for error-tolerant reverse lookup, and in any case it would be too
  8749. hyperactivated).
  8750.  
  8751.  
  8752. >    Memory failure (yours, that is)
  8753. The term is in your dictionary but you can’t remember the spelling well
  8754. enough to retrieve it? Here are some guidelines to follow:
  8755. •    Nearly every name in your dictionary will have some distinctive part
  8756.     that uniquely identifies it, both from your point of view and
  8757.     EnterAct’s. Spell the distinctive part right, and you’ve got it.
  8758. •    If a name consists entirely of common words (Handle, Get, etc) you’ll
  8759.     have to spell more of the name correctly to help EnterAct distinguish
  8760.     among the possibilities.
  8761. •    If in doubt, spell it out. If there’s no exact match, EnterAct will
  8762.     try all standard abbreviations of each of the words in the name.
  8763. •    When you abbreviate part of a name in your source code, try to follow
  8764.     one of these standard abbreviation rules: 1) starting from the end of
  8765.     a word, drop vowels, and when all vowels are gone start over at the
  8766.     end and drop consonants; 2) truncate the word without regard for
  8767.     vowels; 3) either of the above rules, but keep the last letter of the
  8768.     word. If you follow any of these rules and leave at least 3 characters
  8769.     in the abbreviation then EnterAct will be able to generate the
  8770.     abbreviation from the full spelling, producing instant lookup (eg
  8771.     commandKey will retrieve cmdKey, by applying rule 1 but keeping the
  8772.     last letter of command).
  8773. •    If lookup for the name is immediate but wrong, add a spurious
  8774.     uncommon character at the beginning of the name and try again (if name
  8775.     doesn’t work try zname or xname to force a full search).
  8776. •    Use the Options dialog to increase the number of entries kept per
  8777.     lookup window to 10 or more, and try again.
  8778. •    A single case error will be shrugged off, but otherwise regular
  8779.     lookup is case–sensitive (eg CmdKey or cmdkey will retrieve cmdKey
  8780.     immediately, but CMdKey or CMDKey won’t). If you think you have several
  8781.     case errors, try “sounds like” (<Option><Enter>) lookup instead of
  8782.     regular lookup.
  8783.  
  8784.  
  8785. >    Lookup fails
  8786. You know the term should be in your dictionary but even typing its
  8787. exact name doesn’t retrieve it? This is rare, and is caused by EnterAct
  8788. misinterpreting an error in your source code. Looking at the statement
  8789. where the term is defined or mentioned in your source code will usually
  8790. reveal a simple error such as a missing semicolon or a misspelled
  8791. keyword. If not, switch to your compiler and compile your code until
  8792. you’ve cleared any bugs in the statement where the term occurs.
  8793.  
  8794.  
  8795. >    Miscellaneous lookup problems
  8796. In the rare case that your dictionary is small and the name you type
  8797. doesn’t match any term in the dictionary to any reasonable extent,
  8798. you’ll just hear a beep and no lookup will appear.
  8799.  
  8800. The hint for #defined macros is the same as the hint for other
  8801. #defines—add a '#' after the name, rather than a '('. In general, if
  8802. the lookup you see is not what you wanted and you supplied a
  8803. one–character hint, try again without the hint.
  8804.  
  8805. Looking up classes and methods is discussed in more detail in the
  8806. “Browsing” chapter.
  8807.  
  8808. If you suspect your spelling may be way off, try increasing the “Number
  8809. of entries per lookup window” in the Options dialog to 10 or more, and
  8810. then try the lookup again.
  8811.  
  8812. If you’re quite sure that a term should be in your dictionary but it
  8813. doesn’t appear when you look it up, take a look at the statement where
  8814. the term is defined or mentioned: you could have accidentally violated
  8815. a required coding convention (unlikely), or you could have a succession
  8816. of first–draft errors that has confused EnterAct. A missing semicolon
  8817. or misspelled keyword can sometimes result in a term being skipped.
  8818.  
  8819. If you employ macro’s to do such things as optionally include or omit
  8820. full prototypes, or typedef’s, then you should register them with
  8821. EnterAct using the Macro's to skip command, as described in the “Source
  8822. code restrictions” chapter.
  8823.  
  8824. If you run into a problem that stumps you, please compile your code
  8825. before calling for help. However, if you end up fixing bugs in your code
  8826. that you feel EnterAct should have been able to tolerate, please call
  8827. and let me know. kearle@interlog.com.
  8828.  
  8829.  
  8830. §    Editing problems
  8831. EnterAct has a single level of undo, and the window that the undo
  8832. applies to must be in front in order for the Undo command to be
  8833. enabled. 
  8834.  
  8835. To undo a Paste Selection Behind, the window pasted into must be in
  8836. front, and the window copied from must be just beneath, the way
  8837. EnterAct leaves them after carrying out the command. If you can
  8838. remember which two windows were involved in the Paste Selection Behind,
  8839. just bring them to the front alternately until the Undo is enabled.
  8840.  
  8841. If Paste doesn’t preserve your indentation, it’s because you’re leaving
  8842. some text at the left of the first line unselected when you select a
  8843. range or insertion point for the Paste. In particular, Paste won’t
  8844. preserve indentation if you select an insertion point for the Paste
  8845. that is to the right of the first visible character on the line
  8846. (“visible character” here meaning something that is not a space or
  8847. tab). While we’re on the subject, you can switch off the preservation
  8848. of indentation for a Paste by typing a single character just before
  8849. you Paste, and then deleting it after.
  8850.  
  8851.  
  8852. §    Balance problems
  8853. If lack of balance is caused by mismatched delimiters, such as '{'
  8854. matched against ']', then by repeatedly selecting Balance you can
  8855. toggle between the two mismatched delimiters.
  8856.  
  8857. If the unbalance is due to a missing delimiter, keep in mind that
  8858. EnterAct handles comments properly, so the error will not be due to
  8859. an extra delimiter inside a comment. For example, a comment such as
  8860. ____
  8861.     /* 1) load
  8862.         2) decrement
  8863.         3) store
  8864.     */ 
  8865. ____
  8866. won’t trigger an error, unless you start with an insertion point or
  8867. selection that is inside the comment.
  8868.  
  8869. If you’re attempting to balance a closing delimiter and Balance has
  8870. to run backwards through an “asm {..}” block while searching for the
  8871. matching opener, you might get a spurious error due to something in
  8872. an assembly–language comment—see the “Balance” chapter in “The asm
  8873. problem” section for details.
  8874.  
  8875. If the problem is due to consecutive comment starts, and you want to
  8876. keep them because that’s the way you do things, select Options from
  8877. the Edit menu and uncheck the “Detect nested comment starts” check box.
  8878. This will partially disable EnterAct’s ability to trap comment
  8879. problems, both when building your dictionary and when balancing.
  8880.  
  8881. When you Balance an entire file, you will hear a beep whether or not
  8882. the file balanced, just to tell you that the balancing is finished.
  8883. If the cursor doesn’t move from the top of the file, that means the
  8884. entire file is balanced. If there is any error in the file, you will
  8885. be shown the first unbalanced delimiter.
  8886.  
  8887. When balancing just part of a file, you will hear a beep only if there
  8888. is an error. Otherwise, the selection range will quietly expand to the
  8889. next largest balanced range. If there is no larger enclosing range
  8890. (this is the case when you start with an entire function body selected,
  8891. for example) you’ll hear a beep but the selection range will not change
  8892.  
  8893. With the exception of strings, only two types of balance errors can
  8894. occur; mismatched ends, and missing ends. If Balance beeps and shows
  8895. you an unbalanced delimiter, try immediately selecting Balance again.
  8896. Then, if the problem is due to mismatched delimiters, you will be shown
  8897. the other end. If the problem is a missing end, nothing new will
  8898. happen—you’ll hear another beep, but the selected delimiter will not
  8899. change.
  8900.  
  8901. Strings in double quotes " " are checked for one additional special
  8902. error, a missing backslash if the string is continued across lines.
  8903. The backslash must be the very last character on the continued line,
  8904. just before the <Return>—note that even a space before the <Return>
  8905. will “hide” the backslash. Personally, I don’t think this is
  8906. reasonable, but that’s the way C is.
  8907.  
  8908. -    -    -    -    -    -    -    -    -    -    -    -
  8909. License agreement, tech support
  8910. -    -    -    -    -    -    -    -    -    -    -    -
  8911. §    Technical support
  8912. You can reach me (Ken Earle) at:
  8913. ____
  8914.  
  8915. kearle@interlog.com                                via InterNet.
  8916.  
  8917. INTERNET:kearle@interlog.com                via CompuServe,
  8918.  
  8919. or via real-mail at:
  8920. Ken Earle
  8921. 697 Spadina Ave
  8922. Toronto, Ont
  8923. Canada M5S 2J1
  8924. ____
  8925.  
  8926. (reply will be by e-mail, so please include an email address).
  8927.  
  8928. §    License
  8929. By using EnterAct, you are agreeing to abide by the
  8930. terms of this license. If you disagree, don't use it. If you agree,
  8931. send money, then come to disagree and want your money
  8932. back—well heck, everybody makes mistakes now and then,
  8933. just let me know what the problem is and you'll get your
  8934. refund. Do so within 60 days though, else I may deem that
  8935. EnterAct in your hands has already paid for itself several
  8936. times over.
  8937.  
  8938. This version of EnterAct carries a charge of zero dollars and
  8939. zero cents Canadian, so sending that in is optional. Site licence
  8940. discounts are available.
  8941.  
  8942. Neither Apple Computer, Inc., nor any other company makes any
  8943. warranties, either express or implied, regarding the enclosed computer
  8944. software, its merchantibility, or its fitness for any particular
  8945. purpose. The exclusion of implied warranties is not permitted by some
  8946. governments. The above exclusion may not apply to you. This warranty
  8947. provides you with specific legal rights. There may be other rights that
  8948. you may have which vary according to location.
  8949.  
  8950. EnterAct and this manual are copyrighted, with all rights reserved.
  8951. You may distribute full copies of EnterAct (omitting no files from
  8952. the compressed archive that comprises EnterAct), provided you
  8953. do not charge for EnterAct itself.
  8954.  
  8955. In no event shall Dynabyte or any other legal entity involved in the
  8956. creation, production, or delivery of this product be liable for any
  8957. direct, indirect, consequential, or incidental damages (including loss
  8958. of data, lost business profits, business interruption, carpal tunnel
  8959. syndrome, and the like) arising out of the use of or inability to use the
  8960. software or accompanying material.
  8961.  
  8962. EnterAct does not support shared file access. If you use EnterAct on
  8963. a network, or as a member of a team working on the same source,
  8964. be aware that EnterAct will allow two or more people to open
  8965. one file with full read/write access. You must use some separate
  8966. form of source code control to avoid losing or accidentally
  8967. generating variant versions of files. I have done this, by the way,
  8968. with SourceServer, and everything worked fine.
  8969.  
  8970. This agreement will be governed by the laws of the Province of Ontario
  8971.  
  8972. "hAWK", "Read Resource", their associated source code and
  8973. manuals, and the Drag_on Modules interface are yours to keep,
  8974. free, no matter what. They are governed by the Free Software
  8975. Foundation's "copyleft", as described in the document "copying
  8976. hAWK", included with your EnterAct package.
  8977.  
  8978. -    -    -    -    -    -    -    -    -    -    -    -
  8979. Appendix 1 Drag_on Modules
  8980. -    -    -    -    -    -    -    -    -    -    -    -
  8981.  
  8982. Drag_on Modules resemble HyperCard XCMD’s and MPW tools in that
  8983. they are separately–compiled chunks of code that are designed to
  8984. be called from within some application. The calling application is
  8985. at liberty to provide any of a dozen or so callback functions, which
  8986. mainly enhance text–oriented communication between the calling
  8987. application and Drag_on Modules, but these are all optional. The
  8988. calling interface has been kept simple, so that if you have an
  8989. application written in C or C++ you can add to it the ability to call
  8990. Drag_on Modules without hurting yourself—a day or two should do
  8991. it. Instructions for doing so can be found towards the end of the
  8992. “hAWK User’s Manual” and in the file “Call_Resource.c”. The
  8993. source code for “Minimal App7" illustrates the basic process. As
  8994. far as the callback functions go, if your application deals with
  8995. TEXT documents you’ll be able to support most of them easily, and
  8996. if you can’t support one then the Drag_on Modules will get along
  8997. without it.
  8998.  
  8999. The idea behind Drag_on Modules is to provide a medium for the
  9000. inexpensive modular distribution of source code that works best
  9001. when it is allowed to interact with full applications. Drag_on
  9002. Modules could easily be repackaged as separate applications, but
  9003. then the interaction with other applications would be slower. In
  9004. the absence of a universal “shell”, the next–best solution offered
  9005. by Drag_on Modules and the like is to let each application be a
  9006. shell. Admittedly, System 7 has promise as a universal application
  9007. coordinator, but while we’re waiting it’s nice to be able to achieve
  9008. the same effect with just 2K of overhead per application and the
  9009. extreme simplicity of file–based communication for major input
  9010. and output.
  9011.  
  9012. To help the illusion that there is a shell lurking in the background,
  9013. Drag_on Modules communicate by means of standard input, output, and
  9014. error files. This allows results from one Drag_on Module run to be
  9015. passed as input to a subsequent run, for example.
  9016.  
  9017. Two Drag_on Modules are currently being shipped, hAWK and Read
  9018. Resource.
  9019.  
  9020. Read Resource is just a simple resource or data fork viewer.
  9021.  
  9022. hAWK is a Mac implementation of AWK. You may have seen above
  9023. that hAWK has a "three clicks and Run" interface, and it's true:
  9024. for example, you could select hundreds of file as input to a
  9025. hAWK program by putting bullets beside them in your project
  9026. window, and then to call up the program: select "hAWK" from
  9027. the EnterAct menu; pick your program from the top popup;
  9028. optionally adjust the input option (all or part of the front file,
  9029. MFS-selected (ie bulleted) files, or a specific file -- this option
  9030. can be saved with the program, so normally there is no need to
  9031. change it); and then click Run. The program will run in the
  9032. background as you continue to work with EnterAct.
  9033.  
  9034. Added for version 3, you can now write hAWK programs that
  9035. watch EnterAct's clipboard, and, when your specified conditions
  9036. are met, write anything you like back to the clipboard. This
  9037. gives you in effect a "magic clipboard", ideal for reducing
  9038. repetitive, moderately complicated tasks to a simple Copy
  9039. and Paste. For details see the separate document
  9040. "EnterAct's magic clipboard".
  9041.  
  9042. And in version 3.6, a hAWK program can be invoked by placing
  9043. a command line for the program in any EnterAct text window and
  9044. then  pressing <enter> or <command><return> with the command line
  9045. selected. For an example, see "§    Code templates" in the Editing chapter
  9046. above. For details, see "Appendix 2 Calling hAWK programs" just below.
  9047.  
  9048. Drag_on Modules come with complete source code. Complete code and
  9049. instructions for calling Drag_on Modules from your own application can
  9050. be found in the file “Call_Resource.c”, as supplemented by the example
  9051. of “Minimal App7".  If you are interested in creating your own Drag_on
  9052. Module, please see the “write your own Drag_on” folder.
  9053.  
  9054. -    -    -    -    -    -    -    -    -    -    -    -    -    -    -    -
  9055. Appendix 2 Calling hAWK programs
  9056. -    -    -    -    -    -    -    -    -    -    -    -    -    -    -    -
  9057. hAWK programs can be called via a dialog, by picking "hAWK" from
  9058. the EnterAct menu, or by entering a command line in any text
  9059. window. The "hAWK User's Manual" explains how to write hAWK
  9060. programs, and also how to run programs via the dialog. If you like
  9061. the idea of being a power EnterAct user, the section below called
  9062. "Calling hAWK with a command line" will have you firing off
  9063. hAWK programs by typing a few characters.
  9064.  
  9065. §    Calling hAWK from the menu
  9066. EnterAct follows the procedure described in the hAWK User's Manual,
  9067. in the chapter "Running hAWK programs". The "MFS selected files"
  9068. input option corresponds to the bulleted text files in your current
  9069. EnterAct project (you can put bullets (•) beside project file names by
  9070. using the buttons in the Find dialog, or by <option>dragging in the
  9071. project window). Your hAWK program will run in the background
  9072. by default, so you can continue working in EnterAct while running
  9073. a lengthy program.
  9074.  
  9075. If you're using EnterAct to view this and have installed the
  9076. Drag_on Modules folder, give hAWK a try right now:
  9077.     •    put some bullets beside some file names in your project window
  9078.     (if you don't have a project yet, please read at least "EnterAct in
  9079.     brief" to get going)
  9080.     •    select "hAWK" from the EnterAct menu
  9081.     •    pick the program "$EchoFullPathNames" from the top popup
  9082.     menu in the resulting setup dialog
  9083.     •    click the Run button
  9084.     •    the stdout window will appear after a couple of seconds,
  9085.     holding a list of the full path names for your selected project
  9086.     files.
  9087.  
  9088. If you're intrigued, please see the hAWK User's Manual for details.
  9089.  
  9090. §    Calling hAWK with a command line
  9091. If you need to regularly run a hAWK program, and it doesn't take
  9092. its input from the front text window, you might find it handier
  9093. to run it with a command line. Command lines aren't too nasty
  9094. to construct, and you'll only have to do it once for each program
  9095. if you create a code template for the command line. There
  9096. are examples below, and it really is fairly easy.
  9097.  
  9098. You can enter a hAWK command line in any text window. To run it,
  9099. select the entire command line and press <command><return>
  9100. or <enter>. This will run the hAWK program immediately, without
  9101. any setup dialog to go through. Hey, that's the whole point.....
  9102.  
  9103. First let's build hAWK command lines. This is the format of a hAWK
  9104. command line (note it can cover several lines):
  9105. ____
  9106. hAWK -f"Program Name" -f"Library Name"
  9107.     -s -ss -n
  9108.     -vVariableName="some value" -- MFS "InputFullPathname"
  9109. ____
  9110.  
  9111. and this is what that means:
  9112.     •    the command line text must begin with "hAWK" followed by a space
  9113.     or tab
  9114.     •    there must be one program name, as signalled by -f. If you just supply
  9115.     a simple program name, it must reside in the "hAWK programs" folder.
  9116.     Use a full path name if the program is in some other folder. If the
  9117.     program name (or any part of the full path name) contains a space, then
  9118.     put quotes "" around the full name, otherwise the quotes are not needed.
  9119.     •    the library names are the same as program name, and these are
  9120.     optional. Since library names look the same as the program name, the
  9121.     first one seen is taken as the program name. Libraries are scarce as
  9122.     hen's teeth, so forget about them.
  9123.     •    variables are signalled by the -v option, eg -vmyName="Ken E" or
  9124.     -vLevel=1 where the quotes "" are optional if the value contains no
  9125.     spaces or tabs. Spaces before the '=' sign are optional, but don't put any
  9126.     between the '=' and the actual value. Variables are optional. In
  9127.     particular, any variable settings that have been saved with the program
  9128.     (by using the setup dialog) will automatically be passed along with the
  9129.     command line, and so you should set these variables on the command
  9130.     line only if you want to override the default saved values (to see those,
  9131.     select the program in the setup dialog and click the "Set variables..."
  9132.     button).
  9133.     •    "--" signals that input files only follow. This is optional, mainly to
  9134.     make reading easier.
  9135.     •    "MFS" stands for "all files currently selected for multi-file
  9136.     operations", in other words the bulleted files in your project
  9137.     window as you're no doubt tired of hearing. This one is optional.
  9138.     •    input file names are optional, and should be provided as full path
  9139.     names. If any part of the full name contains a space then the quotes ""
  9140.     are necessary, otherwise they're optional.
  9141.  
  9142.     You may also optionally use the following output options (ugh was
  9143.     that English?) in the command line (place them before any "--"):
  9144.     •    -s means show stdout when done
  9145.     •    -ss means show and select stdout when done
  9146.     •    -n means no showing of stdout when done.
  9147.  
  9148. If you don't provide an output option, any output option from the
  9149. settings saved with the program will be used instead (these correspond
  9150. to the "Show/select stdout" checkboxes in the setup dialog). Any output
  9151. option you do provide overrides the saved settings.
  9152.  
  9153. You may supply both "MFS" and one or more specific input files on a
  9154. command line, and unlike the dialog approach you may supply any
  9155. number of variables (the dialog is limited to 10).
  9156.  
  9157. Here are some example command lines:
  9158. ____
  9159. hAWK -f$EchoFullPathNames -- MFS
  9160.  
  9161. hAWK -f$BoilerPlate -vputInComment=1 -vfile="@.c"
  9162.     -vauthor="KE" -vcompany="bdibdi" -ss
  9163.  
  9164. hAWK -f$FormatFunctionIntro
  9165.  
  9166. hAWK -f"Disk:Folder:$SomeProgram" -- "Disk:Folder2:OneInputFile"
  9167.     "Disk:Folder3:AnotherInputFile"
  9168. ____
  9169. The first three there are real hAWK programs supplied with EnterAct,
  9170. and if you take a look at the programs themselves it will help you
  9171. see what happens with each command line. The last one is made up.
  9172. "bdibdi" is pronounced "two little bdi's".
  9173.  
  9174. Now the point of this, as mentioned, is to bypass the setup dialog
  9175. and call a hAWK program with just a few keystrokes. Since command
  9176. lines are more than a few keys long, there are two approaches you can
  9177. take to avoid retyping them:
  9178.     •    save them all in a file, and then select them when needed
  9179.     •    create a code template with a nice mnemonic name for each
  9180.     command line. This is the handiest approach, provided you don't
  9181.     have several dozen programs you want to run regularly.
  9182.  
  9183. Code templates are explained in the "Code templates" section of the
  9184. "Editing" chapter, in fact they're nicely explained at the top of the
  9185. "EnterAct Code Templates" file which is where they all live. This is
  9186. essentially a glossary capability, and to use an entry you type its
  9187. name and press <command><return> to expand it. Code templates know
  9188. about hAWK templates, and if an entry expands to a hAWK template
  9189. then it will be selected for you. To run the template, you press
  9190. <command><return> a second time.
  9191.  
  9192. Here's a typical code template for a hAWK command line, taken from
  9193. the EnterAct Code Templates file:
  9194. ____
  9195. ENTRY
  9196. echo
  9197. hAWK -f$EchoFullPathNames -- MFS
  9198.  
  9199. END
  9200. ____
  9201. This means you can get a list of full path names for bulleted files in
  9202. your project by typing "echo" and then pressing <command><return>
  9203. twice. The first <command><return> replaces "echo" with the
  9204. command line, and selects it: the second <command><return> runs
  9205. the hAWK program "$EchoFullPathNames".
  9206.  
  9207. To try one out for yourself, open up the EnterAct Code Templates file,
  9208. scroll down just a little bit to the "boiler" entry, and change the
  9209. values of the "author" and "company" variables to suit your taste.
  9210. Save the Templates file, and then (immediately) in any text window
  9211. type "boiler" and press <command><return> twice. See what you get.
  9212.  
  9213. Not that tough after all.
  9214.  
  9215. -    -    -    -    -    -    -    -    -    -    -    -    -    -    -    -
  9216. Appendix 4 EnterAct as THINK's editor
  9217. -    -    -    -    -    -    -    -    -    -    -    -    -    -    -    -
  9218.  
  9219. EnterAct can be used as a replacement for THINK’s own internal editor.
  9220. This means you can take full advantage of EnterAct’s features when
  9221. creating your documentation and source, and the THINK Project Manager
  9222. will be able to track all the changes you make as though you were using
  9223. its own editor.
  9224.  
  9225.  
  9226. §    Requirements
  9227. To use EnterAct as a replacement for THINK’s own internal editor, you
  9228. must have:
  9229. •    EnterAct 2.5 or later (you do)
  9230. •    THINK C 6 or later
  9231. •    System 7
  9232. •    about 2 Megabytes each for the THINK Project Manager and EnterAct.
  9233.  
  9234. §    Installing EnterAct as THINK’s editor
  9235. Create an alias of EnterAct, rename it “Editor”, and drop it into
  9236. the “Tools” or “(Tools)” folder inside your THINK C folder. Then
  9237. start up THINK Project Manager, and under the Project Managers’s
  9238. Editor options select “use external editor”—you’ll find this under
  9239. the Edit menu, in the “Editor” options for the Project Manager.
  9240. Recommended, deselect the “Reopen files” option in THINK’s Editor
  9241. options at this point, since EnterAct does a more thorough job of
  9242. reopening EnterAct project files, and this should prove to be all
  9243. you need.
  9244.  
  9245.  
  9246. §    Starting a session
  9247. Start the THINK Project Manager and open a THINK project in your usual
  9248. way. The first action you undertake that requires viewing a text file
  9249. will trigger THINK to start EnterAct. Most often you’ll double-click
  9250. on a file listed in your THINK project, but you might also select the
  9251. “Open” command, or double-click on the result of a batch find to view
  9252. a particular instance, etc. In all cases, when EnterAct starts up you
  9253. will be offered the opportunity to open an existing EnterAct project
  9254. or create a new one. After you’ve opened or created a project, or
  9255. cancelled, the text file will open in EnterAct.
  9256.  
  9257.  
  9258. §    Working with EnterAct as THINK’s editor
  9259. EnterAct and THINK projects serve different purposes, and typically
  9260. even hold different lists of files—an EnterAct project, for example,
  9261. can contain source files that are included for reference only, and
  9262. system and other header files can be explicitly listed in the project
  9263. window, and your dictionary updated for them, right from the moment
  9264. you create the project. So you’ll need an EnterAct project to handle
  9265. your code creation, documentation, and review, and a THINK project to
  9266. handle compiling and testing.
  9267.  
  9268.  
  9269. For the most part, when you want to compile or test you should be in
  9270. THINK, and when you want to edit or view files you should be in
  9271. EnterAct. To switch from EnterAct to THINK, click in your THINK project
  9272. window. To return to EnterAct, click in your EnterAct project window,
  9273. or any open text window that belongs to EnterAct. Though EnterAct may
  9274. be more tightly coupled to THINK in future versions, this simple
  9275. approach has the advantage that all of the THINK commands you use
  9276. regularly are still where you expect under your THINK menus, with one
  9277. extra click on your THINK project window required to place you back
  9278. in the right context for them.
  9279.  
  9280. Of course, opening any text file when in THINK will automatically
  9281. switch you over to EnterAct in order to display the file. And if a file
  9282. is listed in both your THINK and EnterAct projects, you can
  9283. double-click on either instance to open the file, with the same results
  9284.  
  9285. If all of your changes to source files have been made with EnterAct
  9286. acting as THINK’s replacement editor, or with THINK’s own editor, then
  9287. you can bring your THINK project fully up to date with the “Bring Up
  9288. To Date” command under THINK’s “Project” menu, and there is no need
  9289. to “Make” or “Scan Disk” to detect which files have changed. Your
  9290. EnterAct projects will typically need to be brought up to date only
  9291. for significant changes made outside of function bodies, and if all
  9292. changes were made with EnterAct you can use the Update Dictionary
  9293. command under EnterAct’s “EnterAct” menu.
  9294. Please note that both EnterAct and the THINK Project Manager will
  9295. automatically note changed files only for the project that is currently
  9296. open, and if some other project includes a changed file then you will
  9297. need to use THINK’s “Make” command or EnterAct’s Update Dictionary
  9298. to bring the project fully up to date.
  9299.  
  9300. In brief: there is nothing special you need to do when using EnterAct
  9301. as THINK’s editor.
  9302.  
  9303.  
  9304. §    Using THINK’s Find commands from EnterAct
  9305. Three commands at the bottom of EnterAct’s Search menu allow you to
  9306. invoke THINK’s Find commands: specifically, you can view the next or
  9307. previous matches from a batch find, or call THINK’s “Find In Next File”
  9308. command from EnterAct.
  9309.  
  9310. THINK Find Again and THINK Find Previous refer to the results of a
  9311. batch find done in THINK, and allow you to step through the matches,
  9312. viewing them with EnterAct. The batch find must first be carried out
  9313. in THINK, for which see your THINK User Manual.
  9314.  
  9315. THINK Find In Next File is the equivalent of returning to the THINK
  9316. Project Manager and selecting “Find In Next File”—once again, you will
  9317. need to use THINK’s Find dialog to set up the multi-file search
  9318. beforehand.
  9319.  
  9320. By the way, EnterAct’s own multi-file searching capabilities are
  9321. entirely independent of the THINK Project Manager’s. To do a straight
  9322. multi-file search, you should use EnterAct, since here it is slightly
  9323. easier to set up. For a batch find, you’ll need to set your search up
  9324. in the THINK Project Manager and then use THINK Find Again and THINK
  9325. Find Previous in EnterAct afterwards. (EnterAct also has a batch find,
  9326. but doesn't (yet) have the nifty Find Previous gizmoid. To jump to
  9327. a particular instance of one of EnterAct's finds, click on the line
  9328. reporting the find and use "Go to...".)
  9329.  
  9330. Find in THINK Reference does the same thing as the command of the
  9331. same name in the THINK Project Manager's editor: it passes your
  9332. currently-selected text over to THINK Reference, where you'll be
  9333. shown any entry it has on the name in question. Note this works only
  9334. with THINK Reference version 2 or later. For this command to work,
  9335. you need to have a folder named "Tools" or "(Tools)" next to EnterAct,
  9336. and drop an alias of THINK Reference in it.
  9337.  
  9338. -    -    -    -    -    -    -    -    -    -    -    -    -    -    -    -
  9339. Appendix 5 EnterAct and Code Warrior
  9340. -    -    -    -    -    -    -    -    -    -    -    -    -    -    -    -
  9341. By default, when you open a document and Code Warrior also has the
  9342. document open, EnterAct will put up a dialog giving you the options
  9343. of forcing Code Warrior to save and close the file before EnterAct
  9344. opens it, or of cancelling the Open. If you're not sure, return to
  9345. Code Warrior and decide whether or not to save the file. Note if
  9346. you do click "OK" to have EnterAct tell Code Warrior to save and
  9347. close the file, any changes to the file will not be undoable --after
  9348. all, it's not like editors these days have 10,000-level persistent
  9349. selective undo or anything. But shouldn't they?
  9350.  
  9351. As described elsewhere, EnterAct will by default save all
  9352. documents when you switch out, and refresh them from disk
  9353. when you switch back (only if needed of course). So there is
  9354. no decision to make when editing documents with Code Warrior
  9355. while EnterAct has the same documents open, since EnterAct will
  9356. have already saved them. When you switch back to EnterAct,
  9357. if you left the document open with Code Warrior you'll get that
  9358. dialog asking about forcing Code Warrior to save and close it,
  9359. or if you saved and closed the document before leaving Code Warrior
  9360. then EnterAct will just refresh the document from disk.
  9361.  
  9362. The "default" referred to above is the “Safe switching...” option
  9363. in EnterAct's Options dialog, which is on by default and saves your
  9364. documents when you switch out from EnterAct. Better to save too
  9365. often, since you can always revert with the “Show Activities”
  9366. command and a little cut and paste.
  9367.  
  9368. To use EnterAct as just a looker-upper with Code Warrior, see
  9369. "§    EnterAct as a "definition finder" for other editors" in the Lookup
  9370. chapter.
  9371.  
  9372. You can use EnterAct's multi-file search independently of Code
  9373. Warrior's, and EnterAct's is often handier because you can include
  9374. more files in your EnterAct project (all toolbox headers, or files
  9375. from several separate Code Warrior projects, or all Power Plant
  9376. files, for example).
  9377.  
  9378. -    -    -    -    -    -    -    -    -    -    -    -    -    -    -    -
  9379. Appendix 6 the Scripts menu
  9380. -    -    -    -    -    -    -    -    -    -    -    -    -    -    -    -
  9381. EnterAct itself understands only the four basic Apple events,
  9382. but you can use it to run any compiled AppleScript: just drop
  9383. the script in your "(EnterAct Scripts)" folder and it will
  9384. appear under EnterAct's Scripts menu (the next time you
  9385. start EnterAct). The scripts must be compiled, and should be
  9386. the sort that don't need any parameters or events to get going,
  9387. and that quit when they're done their specific task. Recompiling
  9388. your current CW or Symantec project is an example.
  9389.  
  9390. Any text your script puts in the AppleScript "result" variable
  9391. will be shown to you when the script terminates, in EnterAct's
  9392. stdout window.
  9393.  
  9394. To see it work, try the "Beep Once" script that's supplied. You should
  9395. see the stdout window after you hear a beep.
  9396.  
  9397. Event handling is minimal in EnterAct while a script is running: you
  9398. can interrupt a script with <Command><period>, and switch out of
  9399. EnterAct, but nothing else. The upshot is that scripts are appropriate
  9400. for running within EnterAct if they do something not too lengthy that
  9401. has to be done anyway before you can continue. Scripts that are to
  9402. run all the time or that take a very long time should be run some
  9403. other way (eg by double-clicking on the script itself).
  9404.  
  9405.